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In  this  chapter: 


Typographical  Conventions 1 1 

Feedback 12 


Typographical  Conventions 

Before  you  start  using  this  guide,  it  is  important  to  understand  the  documentation 
conventions  used  in  it. 

The  following  kinds  of  formatting  in  the  text  identify  special  information. 

Formatting  convention  Type  of  Information  Example 


Special  Bold 

Items  you  must  select, 
such  as  menu  options, 
command  buttons,  or 
items  in  a list. 

Go  to  the  System  tab. 

Titles  of  chapters, 
sections,  and  subsections. 

Read  the  Basic 
Administration  chapter. 

Italics 

Used  to  emphasize  the 
importance  of  a point,  to 
introduce  a term  or  to 
designate  a command  line 
placeholder,  which  is  to  be 
replaced  with  a real  name 
or  value. 

The  system  supports  the 
so  called  wildcard 
character  search. 

Monospace 

The  names  of  commands, 
files,  directories,  and 
domain  names. 

The  license  file  is  located 
in  the 

http: //docs/common/ 
licenses  directory. 
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Preface 


Pre format ted 


Preformatted 

Bold 


On-screen  computer 
output  in  your  command- 
line sessions;  source  code 
in  XML,  C++,  or  other 
programming  languages. 

What  you  type,  contrasted 
with  on-screen  computer 
output. 


# Is  -al  /files 

total  14470 


# cd  /root/rpms/php 


CAPITALS 


Names  of  keys  on  the  SHIFT,  CTRL,  ALT 
keyboard. 


KEY+KEY  Key  combinations  for  CTRL+P,  ALT+F4 

which  the  user  must  press 
and  hold  down  one  key 
and  then  press  another. 


Feedback 


If  you  have  found  a mistake  in  this  guide,  or  if  you  have  suggestions  or  ideas  on  how  to 
improve  this  guide,  please  send  your  feedback  using  the  online  form  at 
http://www.parallels.com/en/support/usersdoc/.  Please  include  in  your  report  the 
guide’s  title,  chapter  and  section  titles,  and  the  fragment  of  text  in  which  you  have 
found  an  error. 


Chapter  2 


About  This  Guide 


Welcome  to  the  Parallels  H-Sphere  System  Administrator  Guide.  It  aims  at  system 
administrators  and  explains  how  to  install,  configure  and  maintain  Parallels  H-Sphere 
and  its  components. 


Chapter  3 


Pre-configuration  Wizard 


This  document  explains  how  to  shape  your  Parallels  H-Sphere  cluster,  add  boxes  and 
hosting  services  and  configure  basic  Parallels  H-Sphere  settings  after  Control  Panel 
installation. 


Pre-configuration  Wizard 


15 


Parallels  H-Sphere  Pre-Configuration  Wizard  writes  the  cluster  configuration  into  the 
specially  formatted  config.xml  file  (download  sample  config.xml  from 
http://hsphere.parallels.com/HSdocumentation/xmls/confiq.xml).  The  Configuration  File 
form  on  the  main  page  enables  you  to: 

■ Import:  You  upload  the  prepared  XML  file  from  a local  machine  to  Parallels  H- 
Sphere  and  later  reconfigure  Parallels  H-Sphere  in  the  wizard. 

■ Export:  export  config.xml  with  your  Parallels  H-Sphere  cluster  configuration  to 
your  local  machine. 

■ Restore  to  Default:  choose  this  option  to  recreate  config.xml  and  to  restart 
configuring  Parallels  H-Sphere  cluster  in  the  wizard. 

> To  complete  the  pre-configuration  wizard: 

1 . Click  the  Edit  General  Settings  icon  on  the  right  corner  of  the  General  Settings 
caption  and  fill  in  the  data  on  the  page  that  appears: 

■ System  Domain:  Specify  the  service  domain  name  here. 

■ One  Server  Installation:  check  this  box  if  you  need  a single  server  installation. 

■ Use  NAT  IP  mapping:  Check  this  box  if  you  implement  NAT  (on  page  28)  on  your 
Parallels  H-Sphere. 

Press  Submit  and  return  to  the  main  page  of  the  wizard. 

2.  If  you  choose  multiple  server  installation  mode,  you  will  see  the  Add 
Physical  Server  icon  on  the  right  corner  of  the  Physical  Servers  caption.  Click 
this  icon  and  proceed  to  the  form  for  adding  new  physical  servers  and 
services. 

Here  you  set  physical  server  name,  IP,  root  password  to  connect  to,  and  choose 
which  hosting  services  (CP,  Web,  mail,  DNS,  MySQL,  PostgreSQL)  will  be  installed 
there. 

Note:  At  the  moment,  VPS,  Windows,  MRTG  are  not  installed  via  Parallels  H- 
Sphere  pre-configuration  wizard. 

Choose  Use  defaults  for  this  server  to  apply  default  names  for  Parallels  H-Sphere 
logical  servers  on  this  server.  By  default,  they  are  named  webN,  mailN,  nsN,  mailN, 
mysqlN,  respectively. 

3.  After  you  have  added  physical  servers  into  Parallels  H-Sphere  cluster, 
you  will  see  them  on  the  main  page  of  the  wizard. 

Click  the  Edit  icon  in  front  of  a physical  server  in  the  list  and  edit  logical  server 
parameters.  More  on  Logical  Servers  read  in  Parallels  H-Sphere  Service 
Administrator  Guide. 

4.  After  you  have  done  with  Parallels  H-Sphere  configuration,  press 

Proceed  Installation  Wizard. 

5.  You  will  be  taken  to  the  Confirm  Installation  page.  To  complete  installation 
via  CP  web  interface,  click  Yes,  continue 

6.  On  the  page  that  appears  check  the  servers  you  want  to  be 
updated/installed  and  click  Start. 

To  see  the  update  log,  click  the  server  name  link. 

7.  When  update  is  finished  and  the  light  turns  green,  click  Proceed  to 
complete  installation. 

8.  On  the  page  that  appears,  click  Return  to  Admin  CP. 
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Pre-configuration  Wizard 


You  will  be  taken  to  the  administrator  control  panel  where  you  can  maintain  your 
hosting  business. 

In  this  chapter: 

Parallels  H-Sphere  config.xml 17 


Pre-configuration  Wizard 
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Parallels  H-Sphere  config.xml 

The  config.xml  file  is  used  in  Parallels  H-Sphere  Pre-configuration  Wizard  (on  page 
14).  It  contains  Parallels  H-Sphere  cluster  configuration:  physical  servers  with  their  IPs 
and  root  passwords  to  install  Parallels  H-Sphere  to,  and  logical  servers  to  be  installed 
on  these  boxes. 

During  regular  Parallels  H-Sphere  installation,  config.xml  is  formed  in  Parallels  H- 
Sphere  Pre-Configuration  wizard  in  admin  CP  and  is  temporarily  stored  in  the 
~cpanei/ . settings  directory.  After  completing  Parallels  H-  Sphere  installation  in 
the  postinstall  mode,  installer  removes  this  file.  However,  the  postinstall  mode 
won’t  continue  if  config.xml  is  missing  or  is  different  from  the  one  used  at  the 
installation. 

When  installer  runs  in  the  install  mode,  it  is  required  that  you  specify  location  of  the 
correctly  formed  config.xml.  See  Appendix  B.  Installation  Script  Options  of  Parallels  H- 
Sphere  Control  Panel  Installation  Guide. 

Elements  and  Attributes 

In  the  following  chart  xml  elements  are  marked  in  bold  and  their  attributes — in  italics. 

physicalServers  - a list  of  Parallels  H-Sphere  physical  servers,  each  of  them 
described  as  physicalServer  with  attributes: 

■ id  - id  of  the  physical  server 

■ name  - name  of  the  physical  server 

password  - root  password  to  the  physical  server  Each  physicalServer  contains  ip 
and  logicalServers  elements: 

■ ip  - server  IP  with  attribute: 

■ type  - type  of  the  physical  server 

Element  ip  contains  such  child  elements: 

■ addr  - IP  address 

■ ipExt  - external  IP  for  NAT  mapping 

Note:  If  Parallels  H-Sphere  does  not  use  NAT,  this  child  element  is  redundant. 

■ mask -IP  mask 

■ logicalServers  - a list  of  Parallels  H-Sphere  logical  servers  each  of  them  described 
as  logicalServer  with  attributes: 

■ group  - group  of  the  logical  server 

■ id- id  of  the  logical  server 

■ name  - name  of  the  logical  server 

Each  logicalServer  element  contains  ips  element  - a list  of  IPs,  each  of  them 
described  as  ip  with  the  following  child  elements: 

■ addr  - IP  address 

■ ipExt  - external  IP  for  NAT  mapping 

Note:  If  Parallels  H-Sphere  does  not  use  NAT  this  child  element  is  redundant. 


mask  - IP  mask 
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systemzone  - a Parallels  H-Sphere  DNS  zone 
hsversion  - a Parallels  H-Sphere  version 
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Software  Used  in  Parallels  H-Sphere 

This  chapter  lists  various  types  of  software  used  in  Parallels  H-Sphere. 
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Software  Used  in  Parallels  H-Sphere 


Integrated  Third  Party  Products 

Even  though  we  integrate  or  use  the  below  products  in  Parallels  H-Sphere,  we  do  not 
assume  any  responsibility  for  bugs  in  their  source  code.  Should  you  have  any  problems 
with  these  products,  please  contact  the  developers.  The  packages  are  listed  in  the 
alphabetical  order. 

BS  Counter  http://www.stanback.net/proqramming/bscounter 

"This  is  a web  hit  counter/tracker  written  in  Perl,  features  include:  blocking  of  multiple 
hits  from  the  same  user,  insertion  of  commas,  text-based  or  graphical  modes,  supports 
multiple  counters  from  the  same  script,  and  tracks  users’  browsers,  operating  systems, 
locations,  top  20  referrers,  and  top  20  search  engine  keywords,  (requires  SSI  OR 
GD.pm)” 

ezmlm  http://www.ezmlm.orq 

’’ezmlrn  is  a modern  mailing  list  manager.  Its  purpose  is  to  efficiently  send  a message 
to  a large  number  of  recipients  with  minimal  delay.  It  allows  automated  additions  and 
subtractions  from  the  subscriber  database.  In  addition,  it  may  keep  an  archive  of 
messages.  It  can  also  impose  restrictions  on  what  may  be  sent  or  retrieved  and  by 
whom.  Some  mailing  list  managers  keep  a database  of  subscriber  information  and 
tailor  the  message  specifically  for  each  subscriber,  ezmlm  sends  the  same  message  to 
all  subscribers.  This  is  much  more  efficient.  The  benefits  to  the  user  are  that  on 
average  posts  to  ezmlm  lists  reach  subscribers  much  faster  than  they  would  with  other 
mailing  list  manager.” 

Form  Mail  http://www.scriptarchive.com/formmail.html 

’’FormMail  is  a generic  WWW  form  to  e-mail  gateway,  which  will  parse  the  results  of 
any  form  and  send  them  to  the  specified  user.  This  script  has  many  formatting  and 
operational  options,  most  of  which  can  be  specified  through  the  form,  meaning  you 
don’t  need  any  programming  knowledge  or  multiple  scripts  for  multiple  forms.  This  also 
makes  FormMail  a perfect  system-wide  solution  for  allowing  users  form-based  user 
feedback  capabilities  without  the  risks  of  allowing  freedom  of  CGI  access.” 

Miva  Merchant  http://www.miva.com 

”Miva  Merchant  is  a dynamic  browser  based  storefront  development  and  management 
system  that  allows  merchants  to  create  and  administrate  multiple  online  stores  from 
anywhere  in  the  world.” 

mnoGoSearch  http://www.mnoqosearch.org/ 

’’mnoGoSearch  (formerly  known  as  UdmSearch)  is  a full-featured  web  search  engine 
software  for  intranet  and  internet  servers.  mnoGoSearch  software  has  a number  of 
unique  features,  which  makes  it  appropriate  for  a wide  range  of  applications  from 
search  within  your  site  to  specialized  search  systems  such  as  cooking  recipes  or 
newspaper  searches,  ftp  archive  search,  MP3  search,  news  articles  search  or  even 
national-wide  portal  search  engine.” 

ModLogAn  http://ian.kneschke.de/proiects/modloqan/ 

’’ModLogAn  is  a modular  logfile  analyzer  which  is  able  to  analyze  logfiles  from  15 
different  server  types.” 

MySQL  http://www.mysql.com 

’’MySQL  is  the  world’s  most  popular  open  source  database,  recognized  for  its  speed 
and  reliability.” 
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OpenSSL  http://www.openssl.org 

’’The  OpenSSL  Project  is  a collaborative  effort  to  develop  a robust,  commercial-grade, 
full-featured,  and  Open  Source  toolkit  implementing  the  Secure  Sockets  Layer  (SSL 
v2/v3)  and  Transport  Layer  Security  (TLS  vl)  protocols  as  well  as  a full-strength 
general  purpose  cryptography  library  managed  by  a worldwide  community  of 
volunteers  that  use  the  Internet  to  communicate,  plan,  and  develop  the  OpenSSL 
toolkit  and  its  related  documentation.”  Parallels  H-Sphere  uses  system  OpenSSL 
packages.  Make  sure  you  keep  them  updated.  OpenSSL  packages  are  upgraded  as 
any  other  system  packages. 

osCommerce  http://www.oscommerce.com 

’’osCommerce  is  an  online  shop  e-commerce  solution  under  on  going  development  by 
the  open  source  community.  Its  feature  packed  out-of-the-box  installation  allows  store 
owners  to  setup,  run,  and  maintain  their  online  stores  with  minimum  effort  and  with 
absolutely  no  costs  or  license  fees  involved.” 

phpBB  http://www.phpbb.com 

’’phpBB  is  a high  powered,  fully  scalable,  and  highly  customisable  open-source  bulletin 
board  package.  phpBB  has  a user-friendly  interface,  simple  and  straightforward 
administration  panel,  and  helpful  FAQ.  Based  on  the  powerful  PFIP  server  language 
and  your  choice  of  MySQL,  MS-SQL,  PostgreSQL  or  Access/ODBC  database  servers, 
phpBB  is  the  ideal  free  community  solution  for  all  web  sites.” 

phpMyAdmin  http://www.phpmyadmin.net 

’’phpMyAdmin  is  a tool  written  in  PFIP  intended  to  handle  the  administration  of  MySQL 
over  the  WWW.  Currently  it  can  create  and  drop  databases,  create/drop/alter  tables, 
delete/edit/add  fields,  execute  any  SQL  statement,  manage  keys  on  fields.” 

Urchin  http://www.urchin.com 

’’Urchin  is  the  fastest  and  most  accurate  web  analytics  (web  statistics)  software 
available.”  It  is  a commercial  product  and  is  available  for  Windows  2000,  Linux  RedFlat, 
and  FreeBSD  platforms.” 

WebBBS  http://www.extropia.com/scripts/bbs.html 

’’eXtropia  WebBBS  allows  a user  to  post  messages  as  well  as  post  replies  to  existing 
messages.  WebBBS  keeps  track  of  which  messages  are  posts  and  which  ones  are 
replies  and  displays  them  in  a hierarchical  tree-like  fashion.  Posts  that  start  new  topics 
are  at  the  top  of  each  tree,  and  the  replies  are  shown  indented  beneath  the  original 
posts.” 

WebChat  http://www.extropia.com/opensource.html 

’’eXtropia  WebChat  is  a useful  application  that  allows  a number  of  people  on  the  World 
Wide  Web  to  talk  to  one  another  simultaneously.  The  ability  to  chat  on  the  Web  can  be 
a quick  way  to  hold  a virtual  meeting.” 

WebGuestbook  http://www.extropia.com/opensource.html 

eXtropia  WebGuestbook  is  “configurable  so  that  you  can  specify  what  your  guestbook 
file  looks  like  and  how  the  script-generated  responses  are  displayed.  If  configured  to  do 
so,  WebGuestbook  will  email  the  guestbook  administrator  the  text  of  new  entries  as 
well  as  add  them  to  the  guestbook.  The  script  will  also  respond  to  new  entrants  with  a 
configurable  “Thank  you”  message...  Finally,  the  application  comes  with  the  capability 
of  ‘four  letter  word’  filtering  for  a child-safe  guestbook.  You  can  censor  words  by  adding 
them  to  a list  of  ‘bad  words’.” 

Webalizer  http://www.mrunix.net/webalizer/ 

’’The  Webalizer  is  a fast,  free  web  server  log  file  analysis  program.  It  produces  highly 
detailed,  easily  configurable  usage  reports  in  FITML  format,  for  viewing  with  a standard 
web  browser.” 
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Supplementary  Software 

Apache  http://www.apache.org/ 

The  Apache  web-server  is  used  as  the  back-end  for  all  of  PSoft  applications  running  on 
the  Unix  platform.  More  information  about  configuring  and  maintaining  Apache  is 
available  at  the  Apache  project  site. 

Postgresql  http://www.postaresal.org/ 

While  our  products  are  designed  to  work  with  any  SQL-compliant  database  server, 
PostgreSQL  is  the  server  we  use  for  internal  development  and  testing.  Their  website 
not  only  explains  how  to  properly  set  up  this  free  database,  but  also  has  some 
information  about  SQL  in  general. 

ProFTPD  http://proftpd.net 

’’Highly  configurable  GPL-licensed  FTP  server  software.” 
qmail  http://www.gmail.org/top.html 

’’qmail  is  a secure,  reliable,  efficient,  simple  message  transfer  agent.  It  is  designed  for 
typical  Internet-connected  UNIX  hosts.  As  of  October  2001,  qmail  is  the  second  most 
common  SMTP  server  on  the  Internet,  and  has  by  far  the  fastest  growth  of  any  SMTP 
server.” 

vpopmail  http://www.inter7.com/vpopmail.html 

’’vpopmail  (vchkpw)  is  a collection  of  programs  and  a library  to  automate  the  creation 
and  maintenance  of  virtual  domain  email  configurations  for  qmail  installations  using 
either  a single  UID/GID  or  any  valid  UID/GID  in  /etc/passwd  with  a home  directory. 
Features  are  provided  in  the  library  for  other  applications  which  need  to  maintain  virtual 
domain  email  accounts.  It  supports  named  or  IP-based  domains.  It  works  with 
vqadmin,  qmailadmin,  vqregister,  sqwebmail,  and  courier-imap.  It  supports  MySQL, 
Sybase,  Oracle,  LDAP,  and  file-based  (DJB  constant  database)  authentication.  It 
supports  SMTP  authentication  combined  with  the  qmail-smtp-auth  patch.  It  supports 
user  quotas  and  roaming  users  (SMTP  relay  after  POP  authentication).” 
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Used  Libraries  and  Technologies 

CGI  http://cgi.resourceindex.com 

Free  marker  http://freemarker.sourceforqe.net 

Positive  Software  uses  Freemarker  1 .5.1  template  format  for  Parallels  Pi-Sphere  and 
Parallels  SiteStudio.  Please  refer  to  this  site  for  detailed  information  about  the  format 
and  capabilities  of  Freemarker. 

HTML  http://developer.netscape.com 
Java  1.4  http://www.javasoft.com/ 

Perl  http://www.perl.org/ 

PHP  http://www.php.net/  and  http://www.zend.com/ 

XML  http://www.oasis-open.org/ 


Chapter  5 


Update  of  Operating  Systems 


We  do  not  recommend  major  OS  updates  that  result  in  changing  of  OSCODE  (refer  to 
Appendix  D of  Parallels  H-Sphere  Installation  Guide).  Rather,  perform  server  migration. 
You  can  have  it  done  by  Parallels  H-Sphere  support  team, 
http://www.parallels.com/support/hsphere/,  or  migrate  servers  by  yourself  using  the 
following  manuals: 

■ Moving  Mail  Service  (on  page  171) 

■ Moving  DNS  (on  page  188) 

■ Moving  MySQL  (on  page  202) 

■ Moving  CP  Server  (on  page  93) 

However,  if  you  did  update  your  OS  to  another  major  version,  delete  the  file 

/hsphere/ shared/bin /os code. 

In  this  chapter: 


Updating  FreeBSD  Kernel 25 

Updating  Linux 25 
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Updating  FreeBSD  Kernel 

Parallels  H-Sphere  requires  that  FreeBSD  kernel  be  compiled  with  quota  enabled. 

> To  update  kernel  on  a FreeBSD  server  in  an  Parallels  H-Sphere  cluster: 

1.  Download  and  install  FreeBSD  kernel  sources. 

2.  Under  root,  change  directory  to  /usr/src/sys/i38 6/conf , where 
the  kernel  source  is  located: 

# cd  /usr/src/sys/i386/conf 

3.  In  this  directory,  you  will  have  the  default  generic  kernel 
configuration  file,  and,  if  the  custom  kernel  compilation  has  been 
performed,  a custom  kernel  configuration  file,  for  example  mykernel. 

4.  Open  your  current  kernel  configuration  file  (for  example  mykernel)  and 
add  the  line: 

options  QUOTA 

Important:  We  don’t  recommend  modifying  the  default  generic  file.  Instead,  copy 
its  content  to  a custom  file  (like  mykernel)  and  perform  modifications  there! 

5.  Compile  and  install  the  kernel: 

# /usr/sbin/config  MYKERNEL 

# cd  compile/MYKERNEL 

# make  depend 

# make 

# make  install 

6.  Reboot  FreeBSD  server  to  activate  the  new  kernel  settings. 

For  more  information,  see  generic  instructions  on  Building  and  Installing  a Custom 
Kernel  (http://www.freebsd.org/doc/en  US.IS08859-1/books/handbook/kernelconfiq- 

buildinq.html). 


Updating  Linux 

When  you  update  Linux  automatically  by  means  of  up2date  (on  page  27),  apt-get  (on 
page  27),  SWUP,  yum  (http://linux.duke.edu/proiects/yum/)  or  other  RPM  updaters,  you 
must  beforehand  exclude  some  packages  installed  with  Parallels  Pi-Sphere  from  the 
update  list: 

■ rh-postgres,  postgresql,  postgresql-server,  postgresql-libs  on  CP  and  user 
postgresql  boxes 

■ apache  and  apache-related  packages  on  Parallels  Fl-Sphere  CP,  WEB  and  MAIL 
boxes 

■ proftpd,  frontpage  and  related  packages  on  Parallels  Fl-Sphere  WEB  boxes 

■ qmail,  vpopmail,  ezmlm,  sqwebmail  and  related  packages  on  Parallels  Fl-Sphere 
MAIL  boxes 

■ bind  and  related  packages  on  Parallels  Fl-Sphere  DNS  boxes 
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■ XFree86  or  xorg-xl  1 packages  on  CP.  XFree86-deprecated-libs  (or  xorg-xl  1 - 
deprecated-libs)  with  dependences  should  be  installed.  This  is  critical  particularly 
for  Parallels  SiteStudio. 

■ MySQL-server  on  Parallels  Pi-Sphere  MAIL  and  MySQL  boxes 

Please  note  that  these  packages  are  also  to  be  removed  while  preparing  servers  to 
Parallels  Pi-Sphere  installation. 

If  you  have  accidentally  upgraded  your  RedFlat  without  excluding  these  packages,  you 
need  to  downgrade  PostgreSQL  (on  page  215). 

In  this  section: 


Linux  Up2Date 27 

Linux  Apt-Get 27 
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Linux  Up2Date 

The  up2date  utility  is  used  to  upgrade  the  Linux  Kernel  on  RedHat.  For  generic 
information  on  up2date,  please  read  Upgrading  the  Linux  Kernel  on  Red  Hat  Linux 
Systems  (http://www.redhat.com/support/resources/howto/kernel-upgrade/). 

Prior  to  updating  your  Linux  with  the  up2date  procedure,  make  sure  you  exclude 
specific  Parallels  H-Sphere  related  services  (on  page  25)  from  the  list  of  packages  to 
be  updated. 

Linux  Apt-Get 

Since  the  up2date  (on  page  27)  utility  has  become  a paid  service  by  RedHat,  you  can 
use  the  free  apt-get  utility  instead. 

APT-RPM  is  a port  of  Debian’s  apt  tools  to  a RPM  based  distribution,  apt-get  is  an 
advanced  package  management  utility  front-end  to  easily  perform  package  installation, 
upgrading  and  removal.  Dependencies  are  automatically  handled,  so  if  you  try  to  install 
a package  that  needs  others  to  be  installed,  it  will  download  all  needed  packages  and 
install  them.  More  information  on  apt-get  can  be  found  at  http://apt.freshrpms.net/  or 
http://pt-rpm.tuxfamily.org/. 

Prior  to  updating  your  OS  packages  with  apt-get,  make  sure  you  exclude  specific 
Parallels  H-Sphere-related  services  (on  page  25)  from  the  apt-get  configuration. 

To  exclude  these  packages,  modify  the  corresponding  part  of  your 
/etc/apt/apt . conf  file,  similar  to  this: 

//  Completely  ignore  the  following  packages  (not  regexp) 

//  Ignore  { }; 

Ignore  { “bind-utils”; }; 

//  Do  not  try  to  update  the  following  packages 
//  Hold  { }; 

Hold  { 

”rh-postgres*”; 

’’postgresql*”; 

’’apache*”; 

’’proftp*”; 

"qmail*”; 

’’vpopmail*”; 

’’ezmlrn*”; 

’’sendmail*”; 

’’bind*”; 

”XFree86-base-fonts*”; 

”XFree86-font-utils*”; 

”XFree86-libs*”; 

”XFree86-libs-data*”; 

”XFree86-xfs*”; 

”XFree86-Xvfb*”; 

MySQL*}; 
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Parallels  H-Sphere  supports  NAT  (Network  Address  Translation)  which  allows  you  to 
use  internal  IPs  in  your  local  area  network.  When  configuring  Parallels  H-Sphere,  use 
internal  IPs  in  all  instances,  and  Parallels  H-Sphere  will  convert  them  into  external  IPs 
for  the  DNS  settings  and  control  panel  web  interface. 

> To  enable  NAT  support  in  Parallels  H-Sphere: 

1.  Log  into  Control  Panel  server  as  cpanel  user: 

1 . Log  in  as  root  first: 

$ su  - 

2.  Log  in  as  the  cpanel  user: 

# su  -1  cpanel 

2.  Create  the  ips-map . xml  file  in  the 

~cpanel/ shiva/psof t_conf  ig/  directory  in  the  following  format: 

<ips> 

<ip  ext =" external  ip " int =" internal  ip" /> 

</ ips> 

Example: 

<ips> 

<ip  ext="65 .219.197.236"  int="l 92 . 1 68 . 1 . 27"/> 

<ip  ext ="65. 219. 197. 237"  int="192 . 168 . 1 . 28"/> 

<ip  ext="65 .219.197.238"  int="l 92 . 1 68 . 1 . 2 9"/> 

<ip  ext="65 .219.197.239"  int="l 92 . 1 68 . 1 . 30"/> 

<ip  ext=" 65.219.197.242"  int="l 92 . 1 68 . 1 . 31"/> 

<ip  ext ="65. 219. 197. 243"  int="l 92 . 1 68 . 1 . 32"/> 

<ip  ext="65 .219.197.244"  int="l 92 . 1 68 . 1 . 33"/> 

</ ips> 

3.  Set  the  following  record  in 

~ cpanel / shi va/psof t_conf ig/h sphere .properties: 
IPS-XML-FILENAME  = 

/hsphere/ local /home/ cpanel/ shiva/ psoft  config/ ips-map . xml 

4.  Restart  Parallels  H-Sphere  to  apply  changes.  To  do  this,  run  under 

root: 

For  Linux: 

/etc/rc.d/init.d/httpdcp  stop 
killall  -9  java 
sleep  10 

/etc/rc.d/init.d/httpdcp  start 
For  FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
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killall  -9  java 
sleep  10 

/usr/local/etc/rc.d/apachecp. sh  start 

> To  disable  NAT  support 

1.  Remove  the  line  mentioned  in  step  3 above  from 

hsphe re. properties. 

2.  Restart  Parallels  H-Sphere. 

See  below  for  particular  cases  of  configuring  NAT  in  your  Parallels  H-Sphere  cluster. 

In  this  chapter: 


Configuring  Newly  Installed  H-Sphere  with  NAT  Support 29 

Enabling  NAT  Support  on  a Live  System 30 

Configuring  NAT  Firewall 31 

Migrating  IPs  with  NAT 31 


Configuring  Newly  Installed  H-Sphere  with 
NAT  Support 

> To  configure  newly  Installed  H-Sphere  with  NAT  support: 

1.  Create  ips-map  . xml  file  and  configure  hsphere  .properties  to 
use  it  as  specified  in  the  parent  topic. 

2.  In  the  E.Manager  menu,  add  your  physical  and  logical  servers  with  the 
corresponding  internal  IPs  as  described  in  Parallels  H-Sphere  Adding 
Servers  and  Services  Guide. 

3.  Go  to  E.Manager ->  DNS  Manager  and  add  DNS  records  with  internal  IPs  as 
described  in  DNS  Records  section  of  Parallels  H-Sphere  Service 
Administrator  Guide. 

Note:  Internal  IPs  will  be  transformed  to  the  corresponding  external  IPs  in  DNS 
zones  configuration.  There  will  be  only  external  IPs  in  DNS  zones  configuration. 

Should  you  still  have  problems  with  resolving  your  servers  after  that,  run  DNS  Creator 
(on  page  194)  using  the  following  command  under  the  cpanei  user: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz 
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Enabling  NAT  Support  on  a Live  System 

> To  add  NAT  support  to  a Parallels  H-Sphere  already  configured  with 
external  IPs: 

1.  Create  ips-map.xml  file  and  configure  hsphere .properties  to  use 
it  as  specified  in  the  parent  topic. 

2.  Replace  external  IPs  in  E.Manager  ->  P.Servers  and  L.Servers  with  internal 
IPs. 

Note:  These  internal  IPs  should  be  of  the  same  type  (shared,  dedicated)  as  the 
corresponding  external  IPs. 

Example:  If  there  was  a shared  64.10.10.10  external  IP,  the  corresponding 
192.128.10.10  internal  IP  should  also  be  configured  as  a shared  IP. 

In  such  a case,  there  will  be  no  need  to  recreate  DNS. 

3.  Replace  external  IPs  in  E.Manager  ->  DNS  Manager  with  the  corresponding 
internal  IPs. 

Note:  Internal  IPs  will  be  transformed  to  the  corresponding  external  IPs  in  DNS 
zones  configuration.  There  will  be  only  external  IPs  in  DNS  zones  configuration. 

Should  you  still  have  problems  with  resolving  your  servers  after  that,  run  DNS  Creator 
(on  page  194)  using  the  following  command  under  the  cpanei  user: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz 
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Configuring  NAT  Firewall 

Some  software  (osCommerce,  phpBB,  and  Parallels  SiteStudio)  connects  to  resources 
by  hostname  (web . example . com,  mysqi . example . com).  Since  hostnames  resolve 
to  external  IPs,  you  need  to  configure  your  NAT  firewall  so  that  your  physical  servers 
(web . example . com,  mysqi . example . com)  can  address  themselves  and  each  other 
both  by  external  and  internal  IPs. 

Alternatively,  if  you  have  RedHat  Linux  running  on  all  servers,  you  can  add  the 
following  rule  to  the  iptables  for  each  IP  pair  on  every  single  box: 

iptables  -t  nat  -A  OUTPUT  -p  top  -d  <external>  -j  DNAT — to  <internal> 

For  example: 

iptables  -t  nat  -A  OUTPUT  -p  top  -d  65.219.197.236  -j  DNAT — to  192.168.1 .27  iptables 
-t  nat  -A  OUTPUT  -p  top  -d  65.219.197.237  -j  DNAT— to  192.168.1.28  iptables  -t  nat  -A 
OUTPUT  -p  top  -d  65.219.197.238  -j  DNAT— to  192.168.1.29  iptables  -t  nat  -A 

OUTPUT  -p  top  -d  65.219.197.239  -j  DNAT— to  192.168.1.30  iptables  -t  nat  -A 

OUTPUT -p  top -d  65.219.197.242  -j  DNAT— to  192.168.1.31  iptables  -t  nat  -A 

OUTPUT  -p  top  -d  65.219.197.243  -j  DNAT— to  192.168.1.32  iptables  -t  nat  -A 

OUTPUT  -p  top  -d  65.219.197.244  -j  DNAT— to  192.168.1.33 


Migrating  IPs  with  NAT 


For  IP  migration  with  NAT,  see  the  section  on  changing  IPs  (on  page  39). 
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Server  Time  Synchronization 


This  document  explains  how  to  automate  adjusting  your  servers’  time  through  Network 
Time  Protocol  (NTP).  Server  time  synchronization  prevents  various  errors  that  you  are 
likely  to  run  into  unless  your  servers’  time  is  correct.  Automation  of  server  time 
synchronization  is  implemented  through  setting  up  crontab  task  for  your  NTP  client. 

> To  automate  adjustment  of  your  servers’  time  through  NTP: 

1.  Make  sure  you  have  got  an  NTP  client  software  installed  on  your 
server(s).  If  not,  download  it  from  www.ntp.org. 

2.  Choose  time  server(s)  (on  page  32)  and  add  it  to  your  NTP  client 
configuration. 

3.  Log  into  your  servers  as  root  and  use  the  crontab  -e  command  to 
add  an  NTP  cron  task. 

In  the  following  example  your  server  time  is  checked  with  a time  server 
every  4 hours: 

# date  syncronization 

0 */4  * * * /usr/sbin/ntpdate  ntpsl- { 0 , 1 , 2 } . uni-erlangen . de 
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NTP  Time  Servers 32 


NTP  Time  Servers 


The  following  links  will  take  you  to  the  lists  of  time  server  hosts  to  choose  from. 

■ Public  NTP  Pool  Time  Servers  (http://ntp.isc.org/bin/view/Servers/NTPPoolServers) 

■ Public  NTP  Secondary  (stratum  2)  Time  Servers 
(http://ntp.isc.org/bin/view/Servers/StratumTwoTimeServers) 

■ Public  NTP  Primary  (stratum  1)  Time  Servers 
(http://ntp.isc.org/bin/view/Servers/StratumOneTimeServers) 

To  find  the  time  servers  that  best  suit  your  server  location  and  other  requirements,  go 
to  http://ntp.isc.org/bin/view/Servers/WebSearch 
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Cron  Scripts 


Parallels  H-Sphere  uses  cron  utility  on  Unix  servers  to  schedule  the  automatic  launch 
of  the  Parallels  H-Sphere  scripts  for  updating  system  information,  collecting  traffic, 
analyzing  logs,  etc. 

To  view  the  list  of  cron  jobs  on  a server,  type  the  following  command  under  root  on  this 
server: 

# crontab  -1 

Crontab  enables  you  to  set  the  sequence  and  regularity  of  launching  the  scripts.  To 
edit  crontab  list,  type  the  following  command  under  root: 

# crontab  -u  root  -e 

For  more  details  on  editing  cron,  read  man  5 crontab. 

Below  see  the  list  of  cron  jobs  for  Parallels  H-Sphere  logical  servers. 
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Control  Panel  Server  Crons 33 

Web  Server  Crons 34 

DNS  Server  Cron 34 

Mail  Server  Crons 35 

PostgreSQL/MySQL  Server 35 


Control  Panel  Server  Crons 

30  5 * * * su  -1  cpanel  -c  "java  psoft.hsphere.TrafficLoader" 
0 4 * * * su  -1  cpanel  -c  "java  psoft.hsphere.UsageLoader" 

Here, 

■ Traf  f icLoader  is  the  Parallels  H-Sphere  Java  utility  to  collect  the  traffic  statistics 
from  the  traffic  logs  to  the  Parallels  H-Sphere  database. 

■ UsageLoader  is  the  Parallels  H-Sphere  Java  utility  to  collect  disk  usage  statistics 
into  the  Parallels  H-Sphere  database. 
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Web  Server  Crons 

*/5  * * * * nice  -15  /hsphere/shared/scripts/cron/apache-restart . pi 

20  */ 2 * * * nice  -15  /hsphere/shared/scripts/cron/analyze . pi 

*/5  * * * * /hsphere/shared/scripts/cron/ftp-restart.pl 

0 2 * * * nice  -15  /hsphere/shared/scripts/cron/cron_rotate . pi 

0 3 * * * nice  -15  /hsphere/shared/scripts/cron/f tp_anlz . pi 

0 4 * * * nice  -15  /hsphere/shared/scripts/cron/f tp_anlz_user . pi 

0 6 * * * nice  -15  /hsphere/shared/scripts/cron/mnogosearch_index . pi 

Here, 

■ apache-restart . pi  is  the  Parallels  H-Sphere  script  to  restart  Apache  web 
server;  Apache  is  restarted  only  if  the  /hsphere/ shared/ scripts/ apache- 
reconfig  script  has  been  launched  by  Parallels  H-Sphere  beforehand. 

■ anaiyze.pl  is  the  Parallels  H-Sphere  Perl  script  to  calculate  the  traffic. 

■ ftp-restart  .pi  is  the  Parallels  H-Sphere  script  to  restart  FTP. 

■ cron_rotate.pl  is  the  Parallels  H-Sphere  Perl  script  to  collect  and  rotate  user 
traffic  for  external  traffic  calculation  programs  like  Modlogan,  Webalizer  or  Urchin. 

■ ftp_aniz.pl  is  the  Parallels  H-Sphere  script  to  analyze  virtual  FTP  traffic  and 
write  it  to  the  Parallels  H-Sphere  statistics  directory. 

■ ftp_aniz_user.pl  is  the  Parallels  H-Sphere  script  to  analyze  FTP  traffic  and 
write  it  to  the  Parallels  H-Sphere  statistics  directory. 

■ mnogosearch_index . pi  is  the  Parallels  H-Sphere  Perl  script  to  update  the 
MnoGoSearch  index. 


DNS  Server  Cron 

*/l  * * * * [ "x'ps  -ax  | grep  -v  greplgrep  named'"  = "x"  ] && 
/hsphere/ shared/ scripts/cron/dns_check 

dns_check  is  the  Parallels  H-Sphere  shell  script  to  check  DNS  settings. 
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Mail  Server  Crons 

30  * * * * /hsphere/local/var/vpopmail/bin/clearopensmtp 

*/20  * * * * /hsphere/local/sqwebmail/share/sqwebmail/cleancache . pi 

0 3 * * * nice  -15  /hsphere/shared/scripts/cron/mail_overlimit . pi 

30  3 * * * nice  -15  /hsphere/shared/scripts/cron/mail_anlz . sh 

0 * * * * /hsphere/shared/bin/freshclam— quiet 

Here, 

■ clear opensmtp  is  the  vpopmail  utility  to  clean  smtp  logs. 

■ cleancache . pi  is  the  sqwebmail  utility  to  clean  the  webmail  cache. 

■ mail  overlimit . pi  is  the  Parallels  H-Sphere  Perl  script  to  check  overlimits  on 
the  mail  boxes. 

■ maii  aniz . sh  is  the  Parallels  H-Sphere  Perl  script  to  analyze  qmail  traffic  and 
place  it  into  the  H-Shere  statistics  directory. 

■ f reshclam  is  the  script  to  update  ClamAV  virus  patterns. 


PostgreSQL/MySQL  Server 

10  3 * * * nice  -15  /hsphere/shared/scripts/cron/db_usage . pi 

db_usage.pl  is  the  Parallels  H-Sphere  Perl  script  to  collect  statistics  on  the  database 
usage  for  PostgreSQL  and  MySQL  servers. 
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Traffic  Calculation 

This  chapter  dwells  specifically  on  the  issues  of  traffic  logs  and  traffic  calculation. 

In  this  chapter: 

Checking  Traffic  via  Parallels  H-Sphere  Control  Panel 37 

Checking  Traffic  on  Physical  Servers 37 

Processing  Traffic  by  Crons 38 

Parsing  T raffic  by  T rafficLoader 38 
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Checking  Traffic  via  Parallels  H-Sphere 
Control  Panel 

> To  check  traffic  using  the  control  panel: 

1.  Log  into  your  administrator  control  panel. 

2.  Check  the  traffic  by  going  to  Reports  ->  Transfer  Traffic  Report. 

Read  more  in  Reports  section  of  Parallels  H-Sphere  Service  Administrator  Guide. 


Checking  Traffic  on  Physical  Servers 

Web,  FTP  and  mail  logs  are  located  in  the  /hsphere/iocai/var/statistic 
directory  of  the  corresponding  physical  server. 

Log  are  named  as  follows: 

■ dd.mm.YYYY.txt  - web  logs 

■ dd.mm.YYYY.gst.txt  - ftp  logs 

■ dd . mm . yyyy  . f tp . txt  - virtual  ftp  logs 

■ dd.mm.  YYYY.  qml  - mail  logs 

where  dd.mm.  yyyy  is  the  timestamp  of  log  file  creation  date. 

Here,  mail  logs  are  generated  by  the  qmail  server,  and  ftp  logs  by  the  proftpd  utility. 
Log  files  contain  specially-formatted  information  tabulated  as  follows: 

|name|xFer(kB)|Hits_AII|Hits_HTML| 

Here,  name  is  the  domain  name,  xFer  is  total  traffic  in  kilobytes. 

Processed  traffic  files  are  moved  to  the  /hsphere/local/var/statistic/loaded 
directory  as  . gz  archives. 

Refer  to  section  Winbox  Traffic  Calculation  (on  page  249)  to  find  out  how  traffic  data  on 
Winbox  is  read  using  XMLs. 
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Processing  Traffic  by  Crons 
HTTP  traffic 

Please  refer  to  Web  T raffic  Calculation  (on  page  1 1 6)  for  details. 

User  FTP  traffic 

Cron  runs  the  /hsphere/ shared/ scripts/ cron/ ftp  anlz  user  .pi  script  on 
everyday  basis  for  collecting  user  FTP  traffic. 

ftp  anlz  user  . pi  parses  the  /hsphere/local/var/proftpd/xferlog  FTP 

log  file  and  writes  FTP  traffic  statistics  into  the  timestamp-named 

/hsphere /local/var/ statistic/ dd .mm.  YYYY  . gst . txt  Statistics  files. 

Virtual  FTP  traffic 

Cron  runs  the  /hsphere/ shared/ scripts/ cron/ ftp  anlz  . pi  script  On 
everyday  basis  for  collecting  virtual  FTP  traffic. 

ftp_aniz.pl  parses  the 

/hsphere/local/var/proftpd/logs/ {vhost_id}  . ftp.  log  logs  files  for  each 
virtual  FTP  account  and  writes  traffic  statistics  into  the  timestamp-named 

/hsphere /local/var/ statistic/ dd  .mm.  YYYY  . f tp  . txt  Statistics  files. 

Mail  traffic 

Cron  runs  the  /hsphere/ scripts/ cron/mail  anlz . pi  script  on  everyday  basis 
to  collect  mail  traffic.  The  script  analyzes  the  /var/iog/maiiiog  Qmail  log  file  and 
collects  mail  statistics  into  the  specially  formatted  dd . mm . yyyy  . qmi . txt  files  in  the 
Parallels  Fi-Sphere  statistics  directory  (/hsphere/iocai/var/statistic). 


Parsing  Traffic  by  TrafficLoader 

1.  TrafficLoader  Parallels  H-Sphere  Java  class  is  in  charge  of  parsing  the 
server  traffic.  That’s  how  it  is  launched  by  cron: 

30  5 * * * su  -1  cpanel  -c  'java  psof t . hsphere . TrafficLoader' 

TrafficLoader  processes  Web,  mail,  FTP  and  virtual  FTP  traffic  in  the  formatted 
statistics  files  located  in  the  /hsphere/iocai/var/statistic  directory  and  inserts 
these  lines  into  the  translog  table  of  the  Parallels  H-Sphere  system  database. 

T rafficLoader  also  calls  the  /hsphere/ shared/ scripts/xf er_cat  .pi  script  to 
move  the  already  loaded  statistics  files  to  the 

/hsphere/local/var/statistic/loaded  directory  as  .txt.gz  archives. 
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Restarting  Services 


This  chapter  explains  how  to  start,  stop,  and  restart  daemon  services  on  Parallels  H- 
Sphere  servers  under  Linux  and  FreeBSD. 

Important:  Do  not  stop  services  with  kill,  as  it  may  cause  information  loss!!! 

Note:  You  can  also  restart  services  from  the  Admin  CP  as  described  in  section  System 
Service  Management  of  Parallels  H-Sphere  Service  Administrator  Guide. 

Below  instructions  do  not  apply  to  restarting  DNS  server  (named)  for  Bind  8.x  (on  page 
45). 

> To  start  services,  run: 

Linux: 

# /etc/rc.d/init.d/<SERVICE>  start 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  start 

> To  stop  services,  run: 

Linux: 

# /etc/rc.d/init.d /<SERVICE>  stop 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  stop 

> To  restart  services,  run: 

Linux: 

# /etc/rc.d/init.d /<SERVICE>  restart 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  restart 

An  alternative  method  - and  often  more  appropriate  - is  to  stop  and  then  start  the 
service: 

Linux: 

# /etc/rc.d/init.d/<SERWCE>  stop 

# sleep  10 

# /etc/rc.d/init.d/<SERWCE>  start 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  stop 

# sleep  10 

# /usr/local/etc/rc.d /<SERVICE>  start 
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Note:  While  restarting  Parallels  H-Sphere  (on  page  41),  run  kiliaii  -9  java  after 
you  stop  and  before  you  start  CP. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss! 
Following  are  the  commands  to  put  in  place  of  <SERVICE>\ 


Service 

Linux 

FreeBSD 

Parallels  H-Sphere  (tomcat) 

httpdcp 

apachecp . sh 

Parallels  H-Sphere 

Database 

(PostgreSQL) 

postgre 

sql 

010 .pgsql . s 
h 

Apache 

httpd 

apache . sh 

FTP 

prof tpd 

prof tpd . sh 

Qmail 

qmaild 

qmaild . sh 

SpamAssasin 

spamd 

spamd . sh 

ClamAV 

clamd 

clamd . sh 

PostgreSQL  (User  DB) 

postgre 

sql 

010 .pgsql . s 
h 

MySQL 

mysqld 

mysql- 
server . sh 

DNS  (Bind  9.3  and  up  (on 
page  182)) 

named 

named . sh 

ImapProxy 

imappro 

xy 

imapproxy . s 
h 
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Restarting  Parallels  H-Sphere  Control 
Panel 

> To  restart  Parallels  H-Sphere  Control  Panel: 

1.  Log  into  the  CP  server  as  root. 

2.  Run: 

Linux: 

/etc/rc.d/init.d/httpdcp  stop 
/etc/rc.d/init.d/httpdcp  start 

FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
/usr/local/etc/rc.d/apachecp. sh  start 


Restarting  Parallels  H-Sphere  Database 

Parallels  H-Sphere  database  is  used  to  store  system  data.  It  is  not  used  for  hosting. 
Usually,  it  is  located  on  the  same  server  as  the  control  panel  and  is  installed  and 
executed  under  user  pgsqi  (FreeBSD)  or  postgres  (Linux). 

> To  restart  the  database,  execute: 

Linux: 

# /etc/rc . d/init . d/postgresql  stop 

# sleep  1 

# /etc/rc . d/init . d/postgresql  start 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsqi . sh  stop 

# sleep  1 

# /usr/local/etc/rc . d/010 .pgsqi . sh  start 
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Restarting  Web  Server 

> To  restart  Web  server: 

1.  Login  as  root. 

2.  Execute  the  following  command: 

Linux: 

# /etc/rc . d/init . d/httpd  stop 

# sleep  10 

# /etc/rc . d/init . d/httpd  start 

FreeBSD: 

# /usr/local/etc/rc . d/apache . sh  restart 

> To  restart  FTP,  run: 

Linux: 

# /etc/rc . d/init . d/prof tpd  stop 

# sleep  1 

# /etc/rc . d/init . d/prof tpd  start 

FreeBSD: 

# /usr/local/etc/rc . d/prof tpd  restart 


Restarting  PostgreSQL  Server 

> To  start  PostgreSQL  server,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  start 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsql . sh  start 

> To  stop  PostgreSQL,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  stop 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsql . sh  stop 

> To  restart  PostgreSQL,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  restart 

FreeBSD: 
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# /usr/local/etc/rc . d/010 .pgsql . sh  stop 

# sleep  10 

# /usr/local/etc/rc . d/010 .pgsql . sh  start 
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Restarting  Mail  Server 

> To  restart  the  mail  server 

1.  Login  as  root 

2.  Execute  the  following  command: 

Linux: 

# /etc/rc.d/init.d/qmaild  stop 

# sleep  1 

# /etc/rc.d/init.d/qmaild  start 

FreeBSD: 

# /usr/local/etc/rc . d/qmaild. sh  stop 

# sleep  1 

# /usr/local/etc/rc . d/qmaild. sh  start 


> To  restart  the  auth  daemon  for  sqWebMail  under  Linux,  run: 

# /hsphere/local/sqwebmail/libexec/authlib/authdaemond  restart 


Restarting  MySQL  Server 

> To  start  MySQL  server,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  start 

FreeBSD: 

# /usr/local/etc/rc . d/mysql- server  start 

> To  stop  MySQL,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  stop 

FreeBSD: 

# /usr/local/etc/rc . d/mysql -server  start 

> To  restart  MySQL,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  restart 

FreeBSD: 

# /usr/local/etc/rc . d/mysql -server  stop 

# sleep  10 

# /usr/local/etc/rc . d/mysql -server  start 
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Restarting  Named 

> To  start,  stop,  or  restart  named  on  the  Parallels  H-Sphere  DNS  server: 

1.  Log  in  as  root. 

2.  Run  the  respective  command  below. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss!!! 
Linux: 

Starting:  / etc/ rc . d/ init . d/ named  start 
Stopping:  /etc/rc  . d/init . d/named  stop 
restarting:  /etc/rc.  d/init.  d/named  restart 

FreeBSD: 

For  Bind  9.3  and  up  (on  page  182): 

Starting:  / usr/local/etc/rc . d/named,  sh  start 
Stopping:  /usr/local/etc/rc  . d/named,  sh  stop 
restarting:  /usr/local/etc/rc.  d/named.sh  restart 

For  Bind  8.x: 

Starting:  /usr/sbin/named  -u  named 
Stopping:  /usr/sbin/ndc  stop  -u  named 
restarting:  /usr/sbin/ndc  restart  -u  named 

Warning:  Without  “-u  named”,  the  command  will  run  under  root. 

Usually,  a Parallels  H-Sphere  DNS  server  contains  a cron  DNS  check  which  starts 
every  1 or  2 minutes  and,  if  named  is  not  started,  starts  it.  Therefore,  do  not  feel 
alarmed  if  you  stop  named  and  see  that  it  keeps  working  for  another  several  minutes. 
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Control  Panel  Server 

Control  Panel  (CP)  is  the  Parallels  H-Sphere  logical  representation  for  managing 
servers  and  hosting  resources  via  the  web  interface.  It  is  implemented  as  a Java 
servlet  that  runs  on  its  own  Apache  server.  CP  is  a separate  logical  server  and  is 
included  in  every  Parallels  H-Sphere  configuration. 

In  this  chapter: 

Understanding  Control  Panel  Server  Configuration 47 

Logging  in  as  the  cpanel  User 53 

Logging  into  Parallels  H-Sphere  System  Database 53 

Launching  Control  Panel  Cron  Jobs 53 

Configuring  Tomcat 54 

Running  Java  Command  Line  Tools 57 

Securing  Your  CP  Server  with  SSL 72 

Upgrading  Java 75 

Converting  Parallels  H-Sphere  System  Database  from  MS  SQL  to  PgSQL 78 

Converting  Parallels  H-Sphere  Database  To  UNICODE 80 

Accelerating  Control  Panel 82 

Changing  CP  URL 89 

Migrating  Control  Panel  Server 93 

Generating  SSH  Keys  for  Parallels  H-Sphere  Servers 94 

Encrypting  Trouble  Tickets 96 

Customizing  Domain  Registration  Lookup  Script 99 


Control  Panel  Server 


47 


Understanding  Control  Panel  Server 
Configuration 

This  section  provides  the  necessary  information  you  need  to  know  about  the 
configuration  of  Parallels  H-Sphere  control  panel  server. 

In  this  section: 

Installed  Software 47 

Interaction  Between  Servers 48 

Location  of  CP  Files  and  Directories 48 

The  Parallels  H-Sphere  Configuration  File 49 

Control  Panel  Apache  Server  Configuration 49 

Control  Panel  Back-End  Servlet  Engine 49 

Reseller  Configuration 49 

CP  SSL  Configuration 50 

CP  Apache  Log  Files 50 

CP  Traffic  Calculation 51 

The  Parallels  Pi-Sphere  System  Database 51 

CP  Mail  Queue 52 

Installed  Software 

On  control  panel  server  the  following  software  is  used: 

■ Apache  server  version  1 ,3.x  and  2.2.xSSL  support:  OpenSSL 

■ CP  back-end  servlet  engine:  Jakarta  Tomcat  (on  page  54) 

■ System  database:  PostgreSQL  7.4.x  and  up 

■ SiteStudio  - site  builder  optionally  installed  with  Fl-Sphere  on  the  CP  server. 
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Interaction  Between  Servers 

Servers  in  H-Sphere  clusters  communicate  only  through  the  Control  Panel.  There  is  no 
way  for  servers  like  web  and  DNS  exchange  commands  directly. 

To  communicate  with  Linux/Unix  servers,  CP  uses  Shell  or  Perl  scripts  via  SSH 
protocol  (port  22)  as  the  cpanei  user. 

Communication  between  the  CP  and  Windows  servers  is  performed  through  the  SOAP 
protocol,  http://www.w3.org/TR/soap/,  (port  10125)  which  allows  for  cross-platform 
exchange  of  data  in  XML  documents  via  HTTP. 

Location  of  CP  Files  and  Directories 

By  default,  the  cpanei  user  home  directory  is  /hsphere/local/home/ cpanei. 

There  you  will  find  the  following  files  and  directories: 

■ apache  - CP  Apache  installation 

■ apache/etc  - CP  Apache  configuration 

■ apache/ etc/httpd.  conf  - CP  Apache  configuration  file 

■ shiva  - H-Sphere  related  binary  and  config  files 

■ shiva/psoft  config  - H-Sphere  config  files 

■ shiva/psoft  conf  ig/hsphere  . properties  - H-Sphere  COnfig  file 

■ shiva/psof  t_conf  ig/HS_VERSiON  - file  that  contains  version  number  of  H- 
Sphere 

■ shiva/ shiva-tempiates  - H-Sphere  templates  location,  DocumentRoot  for 
Apache  server. 

■ shiva/shiva-tempiates/index . html  - Redirect  to  control  panel;  served 
when  the  http://cp.domain.com:8080/  CP  URL  is  accessed 

■ /hsphere/shared/SiteStudio/psof t conf ig/masonry . properties  - 

SiteStudio  config  file  (could  be  on  a different  server) 

IMPORTANT:  To  make  changes  in  these  files,  log  into  the  CP  server  as  the  cpanei 
user. 
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The  Parallels  H-Sphere  Configuration  File 

The  H-Sphere  configuration  file  should  be  located  at 

-'-cpanel/ shiva /pso ft  conf ig/hsphere  .properties 

1.  CP  URL  configuration  - URL  by  which  H-Sphere  is  called: 

■ CP  HOST  = cp.domain.com — hostname 

■ CP_PORT  = 84  43  -port 

■ CP_PROTOCOL=https  : //  - protocol 

■ CP  URI  = /psof t/servlet/psof t . hsphere . CP 

Notes: 

■ This  is  not  the  only  place  where  those  settings  have  to  be  altered. 

■ URI  cannot  be  changed  here  at  the  moment. 

■ Make  sure  that  DNS  is  properly  configured  if  you  want  to  change  domain. 

■ Make  sure  to  alter  Apache  if  you  want  to  change  domain  and  port. 

2.  Database  settings 

3.  Log  file: 

log  4 j . appender . A1 . File=/var/ log /hsphere /hsphere  .log  - location  of 
the  log  file. 

Control  Panel  Apache  Server  Configuration 

CP  Apache  home  directory  is  /hsphere/local/home/ cpanel/apache. 

All  CP  Apache  server  configurations  are  placed  into  the  etc/jserv  subdirectory  of 
the  Apache  home  directory:  /hsphere/local/home/ cpanel/apache/ etc/ j serv. 

This  directory  also  has  its  symlink: 

/hsphere/local/home/ cpanel/ apache/ conf. 

Control  Panel  Back-End  Servlet  Engine 

CP  server  uses  Jakarta  Tomcat  servlet  engine  and  is  automatically  installed  with 
Tomcat  (on  page  54)  embedded. 

Reseller  Configuration 

/hsphere/local/home/cpanel/apache/etc/sites/  contains  resellers’  SSL 
and  virtual  host  configuration. 

■ /hsphere/local/home/ cpanel/ apache /etc/ { reseller_main_account_ 
name } . conf  - reseller  Apache  virtual  host  configuration  file. 

■ /hsphere/local/home/ cpanel/ apache /etc/ { reseller_main_account_ 
name } / - reseller  SSL  directory. 

Reseller  SSL  Configuration 

If  SSL  is  enabled  for  reseller,  the  following  files  are  placed  into  the  reseller  SSL 
directory: 
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■ server . crt  - reseller  SSL  certificate 

■ server . key  - reseller  SSL  private  key 


CP  SSL  Configuration 

In  the  /hsphere/iocai/home/ cpanei/apache  CP  Apache  home  directory: 

■ etc/ ssi . crt/ server . crt  - file  with  server  SSL  certificates. 

■ etc/ssi . csr/server . csr  - file  with  SSL  signing  request. 

■ etc/ssl . key/server . key  - file  with  SSL/RSA  private  key. 


CP  Apache  Log  Files 

Log  files  are  located  in  the  /hsphere/ local /home/  cpanel/  apache  /logs 

directory. 


Control  Panel  Server 


51 


CP  Traffic  Calculation 

Traffic  generated  from  browsing  the  Control  Panel  is  not  included  in  the  summary 
traffic.  To  track  it,  Parallels  H-Sphere  owners  may  set  up  any  third-party  utilities. 

The  Parallels  H-Sphere  System  Database 

The  Parallels  H-Sphere  system  database  is  used  to  store  system  data.  In  normal 
Parallels  H-Sphere  configuration,  it  runs  on  PostgreSQL  server.  Usually,  the  system 
database  is  located  on  the  same  server  with  the  Control  Panel. 

The  system  database  is  not  for  user  hosting!  PostgreSQL  hosting  server  cannot  be 
installed  on  the  same  box  with  the  system  database! 

Note:  The  Parallels  H-Sphere  database  is  executed  under  the  pgsqi  or  postgres 
user. 


The  System  Database  Settings 

Database  settings  in  hsphere. properties  (this  should  be  enough  to  connect  to  db): 

DB  DRIVER  = org . postgresql . Driver 

DB_URL  = j dbc  : postgresql : //127 . 0 . 0 . 1/hsphere  - the  System  database 
name,  usually  hsphere 

db_user  = wwwuser  - the  system  db  user  name,  usually  wwwuser 

db_pas sword  = your_db_pas sword  - the  system  db  user  password 
DB_NEWID  = SELECT  nextval ( " { 0 } " ) 

Logging  into  the  System  Database 

> To  log  into  the  system  database: 

1.  Login  as  the  cpanel  user  (on  page  53)  to  the  server  where  the  system 
database  is  located  (usually,  CP  server). 

2.  Enter  the  hsphere  database  (usually,  under  the  wwwuser  user  name): 

# psql  hsphere  [user_name] 

See  also  the  instructions  on: 

■ restarting  the  system  database  (on  page  41) 

■ backing  up  the  system  database  (on  page  325) 

■ upgrading  the  system  PostgreSQL 

■ the  system  database  optimization  (on  page  82) 

■ PostgreSQL  localization  (on  page  212)  (choosing  the  language  for 
PostgreSQL) 

VACUUM  Utility 

The  Postgres  VACUUM  instruction  allows  cleaning  up  the  server  transactions.  Enter 
the  psql  server: 
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# psql  hsphere  wwwuser 

and  type  in  the  password  set  in  hsphere  .properties. 

In  the  psql  command  line,  type  the  ‘vacuum  full’  command: 

vacuum  full; 

The  command  may  vary  in  different  versions  of  Postgres. 

Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete. 


CP  Mail  Queue 

The  mail  queue  file  is  assigned  to  store  unsent  CP  messages  (e.g.,  trouble  tickets, 
system  notifications,  mass  mail,  etc.)  when  CP  is  restarted  - formerly,  they  were  lost 
after  CP  restart.  Mail  queue  location  is  set  in  hsphere  .properties: 

MAIL_SWP=/hsphere/local/home/cpanel/shiva/mail.swp 
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Logging  in  as  the  cpanel  User 

Parallels  H-Sphere  control  panel  runs  under  the  cpanel  user  on  the  CP  server.  You 
need  to  log  in  as  cpanel  to  perform  many  administrative  tasks,  such  as  CP 
configuration,  customization,  access  the  system  database,  running  console  Parallels  hl- 
Sphere  java  tools,  and  many  others. 

Under  cpanel,  Parallels  H-Sphere  control  panel  communicates  with  other  Parallels  hl- 
Sphere  boxes  via  SSH. 

> To  log  in  as  the  cpanel  user: 

1.  Log  in  as  root  first: 

$ su  -l 

2.  Log  in  as  the  cpanel  user: 

# su  -1  cpanel 


Logging  into  Parallels  H-Sphere  System 
Database 


To  run  SQL  queries  against  the  Parallels  H-Sphere  system  database,  you  need  to  be 
logged  into  Parallels  H-Sphere  system  database. 

> To  log  into  Parallels  H-Sphere  System  Database: 

1.  Log  in  as  root  on  the  CP  server: 

$ su  - 

2.  Log  in  as  the  cpanel  user: 

# su  -1  cpanel 

3.  Connect  to  the  system  database: 

# psql  -d  hsphere  wwwuser 


Launching  Control  Panel  Cron  Jobs 

Along  with  the  cron  scripts  (on  page  33)  that  Parallels  H-Sphere  puts  into  its  physical 
servers’  crontabs,  there  are  several  background  jobs  that  are  executed  by  Parallels 
H-Sphere  on  the  Control  Panel  server: 

■ Accounting  - does  recurrent  billing  for  end  users 

■ OverLimitCron  - checks  that  the  account  is  not  going  over  the  limit 

■ ResellerCron  - does  billing  for  resellers 

■ TrialCron  - suspends  expired  trial  accounts 

■ RevenueCron  - calculates  summary  billing  info 

■ ContentMovingCron  - completes  the  process  of  moving  user  content 

■ FailedSignupsCron  - sends  emails  about  failed  signups  (every  5 minutes) 
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■ TTAutocloseCron  - closes  trouble  tickets  answered  certain  time  ago 

■ VPSCron  - queries  the  status  of  creating  virtual  servers  (every  4 minutes) 

■ ecCron  - processes  the  externai_credits  table  and  adds  payments  performed 
within  an  external  payment  system  outside  Parallels  H-Sphere  to  this  table  as  the 
account  credits,  thus  integrating  external  payments  into  Parallels  H-Sphere.  Read 
more  about  external  credits  configuration  in  External  Credits  section  of  Parallels  H- 
Sphere  Developer  Guide. 

These  cron  processes  use  the  iast_start  table  in  the  Parallels  H-Sphere  database. 
This  table  contains  the  following  fields: 

name  varchar(20)  NOT  NULL  PRIMARY  KEY, 
value  timestamp, 
last_user  int8 

When  Parallels  H-Sphere  is  restarted,  the  values  are  read  from  this  table  for  each  cron: 

■ name  - CP  cron  job  name  as  in  the  list  above  (corresponds  to  the  cron  tag’s  name 
attribute  in  cron  XML  configuration  file) 

■ value  - last  time  that  cron  was  executed 

■ iast_user  - userjd  of  the  last  user  that  was  calculated  with  the  cron  (used  only 
for  accounting  and  overlimit). 

CP  Cron  XML  Configuration  Files 

CP  cron  settings  are  defined  and  customized  in  the  corresponding  XML  configuration 
file  described  in  CP  Cron  Configuration  section  of  Parallels  H-Sphere  Developer 
Guide.  You  can  add  new  custom  CP  crons  according  to  the  instructions  from  Adding 
Custom  CP  Cron  Jobs  of  Parallels  H-Sphere  Developer  Guide  and/or  change  cron  job 
settings  such  as  priority,  starting  time  and  period.  Such  customization  can  also  be  done 
by  means  of  Parallels  H-Sphere  packages  (see  Building  Packages  section  of  Parallels 
H-Sphere  Developer  Guide). 

Background  Job  Manager 

Background  Job  Manager  is  a utility  that  allows  you  to  enable,  start  and  disable 
selected  cron  jobs  from  the  CP  interface.  Cron  jobs  are  available  from  the  Admin 
control  panel,  the  Background  Job  System  section. 


Configuring  Tomcat 

Tomcat  installation  is  located  in  the  /hsphere/local/home/ cpanel/ j akarta 

directory. 

Important:  The  core  Parallels  H-Sphere  directories  such  as  shiva,  shiva- 
tempiates,  psoft,  and  psoft-config  are  located  in  the 

/hsphere/local/home/ cpanel/hsphere/WEB-INF/ classes/  directory  with 
Parallels  H-Sphere  classes  run  by  Tomcat.  Symlinks  to  these  new  locations  are  put  in 
place  of  the  old  directories  to  preserve  Parallels  H-Sphere  integrity  with  previous 
versions’  configuration. 
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Tomcat  Configuration  Files 

Tomcat  configuration  files  are  located  in  the 

/hsphere/ local /home/ cpanel/  j akarta/ conf  directory: 

■ /hsphere /local /home/  cpanel/  j akarta/ conf/  server . xml  - XML  config 
file  for  Tomcat; 

■ /hsphere/local/home/cpanel/hsphere/WEB-INF/web . xml  - XML 

configuration  file  where  CP  servlet  configuration  is  set; 

■ /hsphere/local/home/cpanel/apache/etc/mod  j k . conf  - modjk 
configuration,  modjk  is  a Tomcat-Apache  plug-in  that  handles  the  communication 
between  Tomcat  and  Apache.  For  more  details,  see  Apache  documentation  on 
modjk  (http://iakarta.apache.org/tomcat/tomcat-3.3-doc/mod  jk-howto.html). 

Tomcat  Log  File 

Tomcat  log  file  is 

/hsphere /local /home/ cpanel/ j akarta/ logs/ catalina . out. 

Jakarta  connector  log  is 

/hsphere /local /home/ cpanel/ apache /logs /mod  j k . log. 

Restarting  Tomcat 

> To  stop  Tomcat: 

Run: 

/hsphere/local/home/cpanel/ jakarta/bin/catalina . sh  stop 


> To  start  Tomcat: 

Run: 

/hsphere/local/home/cpanel/ jakarta/bin/catalina . sh  start 

Tomcat  is  also  restarted  when  restarting  Parallels  H-Sphere  (Tomcat  is  restarted 
together  with  CP  Apache): 

/etc/init.d/httpdcp  restart 

Note:  Sometimes  you  might  need  to  restart  only  CP  Apache,  keeping  Tomcat  running. 
Then,  use  the  following  option: 

/ etc/init . d/httpdcp  restartapache 

Customizing  Tomcat  Environment  Variables 

The  file  -cpanei/setenv.  sh  is  designed  to  customize  Tomcat  environment 
variables. 

For  example,  to  allocate  Java  memory  in  the  range  between  64  MB  and  512  MB: 

1.  Log  in  as  cpanel  user  (on  page  53)  . 

2.  Stop  Tomcat  as  described  above. 

3.  Open ~cpanel/setenv. sh: 
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• bash-2 . 05b$  vi  ~cpanel/setenv . sh 

Set  the  following  line  in  the  file: 

export  CATALINA_OPTS=" -Xms  64M  -Xmx512M" 

4.  Start  Tomcat.  You  will  see  something  like  this: 

Using  external  settings  -Xms64M  -Xmx512M 
+ java  version  1.4.x 

Using  CATALINA  BASE:  /hsphere/local /home/cpanel / j akarta 
Using  CATALINA  HOME:  /hsphere/local /home/cpanel / j akarta 
Using  CATALINA_TMPDIR : 

/hsphere/local /home/ cpanel/ j akarta/ temp 
Using  JAVA  HOME:  /usr / j ava/ j dk 

5.  Check  Java  to  make  sure  the  custom  settings  are  applied: 

• bash-2. 05b$  ps  auwx  | grep  java 

cpanel  3010  99.9  29.6  436776  27652  pts/0  S 05:54  0:09 
/usr/ j ava/ j dk/bin/ j ava  -Xms64M  -Xmx512M  - 
D j ava . awt . headless=true  - 

D j ava . endorsed. dirs=/hsphere/ local /home/ cpanel/ j akarta/ common 
/endorsed  -classpath 

/usr/ j ava/ j dk/lib/ tools . j ar : /hsphere/local /home/ cpanel/ j akart 

a/bin/bootstrap .jar: /hsphere/local /home/ cpanel/ j 

cpanel  3020  0.0  0.7  3680  664  pts/0  S 05:54  0:00  grep  java 
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Running  Java  Command  Line  Tools 

This  document  lists  java  command  line  tools  that  come  with  the  standard  Parallels  Id- 
Sphere  installation. 

IMPORTANT:  Before  running  a Java  tool,  make  sure  to  log  into  CP  server  as  the 
cpanel  user:  su  -1  cpanel 


In  this  section: 


DNSCreator 58 

IPMigratorFast 59 

PhysicalCreator 60 

PostApacheConfigs 61 

PostFTPConfigs 61 

ServerAliasesRenamer 62 

ChangeLServerld 63 

MIVAEmpresaFix 63 

KeyPairGenerator 64 

PGPEncrypter 64 

PGPMessageSigner 64 

PGPMessageVerify 65 

RepostResellerSSLConfigs 65 

ServiceZoneRenamer 66 

BillingEraser 66 

SetQuota 67 

UrchinReconfig 67 

OffLogs 68 

Reset  Balance 69 

RegeneratelpsFile 70 

LicenseExtractor 70 

MailRelayCorrector 71 
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DNSCreator 

NAME:  psof t . hsphere . tools . DNSCreator  - Parallels  H-Sphere  DNS  zones 
recreator. 

USAGE:  java  -Xms64M  -Xmx512M  psof t . hsphere . tools . DNSCreator  -m 
creation  method  [-dz]  -z  zonename 


OPTIONS: 


■ m|  creation  method.  Possible  values:  db  or  rand: 

■ db  - pick  NS  servers  as  they  are  defined  in  the  Parallels  H-Sphere  database 

■ rand  - pick  NS  servers  randomly 

■ dz  | — deiete_zones  - delete  zones  first.  Add  this  option  only  if  such  zones 
already  exist.  With  this  option,  DNS  creation  will  take  at  least  twice  more  time. 

■ lids  | — logical-servers  - process  zones  which  are  on  the  logical  servers  with 
the  specified  IDs.  (This  option  makes  sense  if  you  have  more  than  four  logical 
name  servers  with  clearly  defined  Used  By  roles.) 

■ pip  | --pServeriP  - specifies  a physical  server  by  its  primary  IP.  All  necessary 
logical  server  IDs  are  chosen  automatically.  Often  -pip  is  used  as  an  alternative  to 
-lids. 

■ z | — zone  - recreate  only  one  specified  zone.  Without  this  option,  all  zones  will  be 
recreated. 

Note:  If  both  lids  and  -z  parameters  are  specified,  the  -z  parameter  will  be 
ignored. 

The  tool  also  accepts  zone  names  separated  by  line  breaks: 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. DNSCreator  -m  creation_method  [-dz]  < 
filename 

where  filename  is  the  name  of  the  file  which  contains  zone  names  separated  by  line 
breaks. 

DNS  Creator  is  used  in  Single  DNS  Configuration  (on  page  185),  Changing  IPs  on 
Systems  Using  NAT  (on  page  39),  Moving  DNS  (on  page  188)  and  in  Moving  Mail 
Accounts  (on  page  174). 
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IPMigratorFast 

NAME:  psoft.hsphere.tools. IPMigratorFast  - Parallels  Pi-Sphere  IP  migration  utility 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  [options] 
ipmigration . 

OPTIONS: 

■ help  - shows  this  screen 

■ ip-change  - Change  IP 

■ repost-configs  - repost  IP  dependemd  resources 

■ recreate-zone  - change  and  repost  DNS  records 

■ service-zone  - change  service  zone  server  IP 

■ custom-rec  - process  service  DNS  records 

■ iServerids=, , . . . , - to  specify  logical  server  ids 

■ repost-cp-ssl  - Repost  SSL  CP  VPIost  configs 

■ clear-oid-ips  - remove  old  ips  from  database  and  servers 
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PhysicalCreator 

Physical  Creator  is  a java  class  that  generates  web  hosting  resources  and 
configurations  on  web,  win,  and  mail  servers  using  the  data  in  the  Parallels  H-Sphere 
system  database.  This  utility  is  used  to  recover  and  migrate  user  accounts.  It  is 
included  into  standard  Parallels  H-Sphere  installation. 

> To  run  Physical  Creator: 

1.  Log  into  the  control  panel  server  as  cpanel  (on  page  53). 

2.  Back  up  the  content  of  the  -cpanel/shiva/psoft/  directory. 

3.  Run  Physical  Creator: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator 
OPTIONS 

where: 

■ xms64M  - recommended  minimum  memory  for  this  process 
xmx5i2M  - recommended  maximum  memory  for  this  process  OPTIONS: 

■ -h  | — help  - shows  the  list  of  available  options 

-rg  | — rgroup  - resource  group  to  perform  operations  with  The  following 
resource  groups  are  allowed: 

■ unixweb  - Unix  virtual  hosting  resources 

■ winweb  - Windows  virtual  hosting  resources 

■ mysql  - MySQL  resources 

■ mail  - Mail  resources 

■ -co  | — create-oniy  - performs  creation  resources  routines  only 

■ -do  | — delete-only  - performs  delete  resources  routines  only 

■ -rc  | — recreate  - performs  both  delete  and  creation  resources  routines 

■ -lid  | — lserverid  - process  accounts  on  logical  server  with  given  number 

■ -accs  | — accounts  - account  IDs  separated  by  comma,  e.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  26  -accs  1725895  > creator.log  2>&1  & 

■ -st  | — start-from  - account  ID.  Process  will  start  from  this  account  ID.  E.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  26  -st  1590055  > creator.log  2>&1  & 

Here  is  another  example  of  the  entire  command: 

bash-2 . 05a$  java  psoft . hsphere . tools . PhysicalCreator  -rg 
unixweb  -co  -lid  25 

This  command  will  create: 

■ empty  home  dirs 

■ default  configuration  of  FTP  and  HTTP  virtual  hosts  on  unix  logical  server  with 
ID  25 

If  PhysicalCreator  hangs  on  one  of  the  accounts,  kill  it,  debug  the  issue,  and  then 
resume  the  process  starting  with  this  account,  e.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  26  -st  1590055  > creator.log  2>&1  & 
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4.  Restore  the  backup  of  the  -cpanel/shiva/psoft/  directory  to  the 
original  (recovery)  or  target  (move)  location. 

5.  Restart  Parallels  H-Sphere  (on  page  41). 

PostApacheConfigs 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PostApacheConfigs  [-lid  n ] 
[ "ic  ] 

■ -lid  | — lserverid  n work  only  on  accounts  on  logical  server  with  passed 
number 

■ -ic  | --initcontent  initialize  content 

■ -h  | — help  print  this  message 


PostFTPConfigs 

NAME: 

psoft . hsphere . tools . PostFTPConfigs  - Parallels  H-Sphere  virtual  FTP  hosts 
generator  utility 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PostFTPConfigs  options 

OPTIONS: 

■ -h  | — help  - shows  this  screen 

■ -acc| — acountid  number  - process  only  account  with  given  number 

■ -lid  | — lserverid  - process  only  accounts  on  logical  server  with  given  number 

■ -all  | — all  - process  all  virtual  FTPs 
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ServerAliasesRenamer 

NAME: 

psof t . h sphere .tools . ServerAliasesRenamer 

This  Parallels  H-Sphere  tool  recreates  server  aliases  for  resellers. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ServerAliasesRenamer 
[options] 

Usage: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ServerAliasesRenamer 

OPTIONS: 

■ --help  - shows  this  screen 

■ — xml  - run  the  tool  for  determined  xml  file 

■ — l server  ...  - run  the  tool  for  determined  Logical  Server  IDs 
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ChangeLServerld 

NAME: 

psof t . hsphere . tools . ChangeLServerld  - changing  logical  server  id  in  Parallels 
H-Sphere  database 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ChangeLServerld 
[options] 

OPTIONS: 

■ --help  - shows  this  screen 

■ -a | — account  ACCOUNT_ID  -f| — from  LOGICAL_SERVER_ID_l  -t  | — to 

L0GICAL_SERVERJD_2 

where 

■ account_id  - id  of  the  account  you  want  to  change; 

■ logi cal_server_i d_i  - id  of  the  logical  server  you  want  to  change  from; 

■ logi cal_server_i d_2  - id  of  the  logical  server  you  want  to  change  to; 


SAMPLE: 

java  -Xms64M  -Xmx512M  psoft. hsphere. tools. ChangeLServerld  -a  1000  -f  1 -t  2 
This  tool  is  also  used  in  Moving  Mail  Accounts  (on  page  174). 


MIVAEmpresaFix 

“MIVAEmpresaFix”  utility. 

■ Adds  MivaEmpresa  resource  to  the  plans 

■ Adds  this  resource  to  users  which  already  have  MivaMerchant  in  use. 

■ Works  for  Unix  and  Windows  plans 


Usage: 


java  -Xms64M  -Xmx512M  psoft . hsphere . tools .MIVAEmpresaFix 
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KeyPairGenerator 

Parallels  H-Sphere  PGP  key  pair  generator. 

USAGE: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . KeyPairGenerator 

■ -i  | — identification  <youridentification  string> 

■ -s  | — subkeyidentif ication  <your  session  key  identification> 

■ -e  | — encryptphrase  <phrase  for  encryption/decryption  private  key> 

■ -prf  | — privatekeyf  ile  <file  where  private  key  will  be  saved> 

■ -pcf  | — pubiickeyf  ile  <file  where  public  key  will  be  saved> 

This  tool  is  used  in  PGP  Encryption  in  Trouble  Tickets  (on  page  96). 


PGPEncrypter 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPEncrypter 

■ -m  “This  is  a message  to  encrypt” 

■ -f  “This  is  a file  where  encrypted  phrase  will  be  saved” 

■ -k  7path/to/PGP_Public_Key/file” 

This  tool  is  used  for  PGP  Encryption  in  Trouble  Tickets  (on  page  96). 


PGPMessageSigner 

Misconfiguration  Parallels  H-Sphere  PGP  message  signer. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPMessageSigner 

■ -m  | — message  <Message  to  sign>  or  -mf|--messagefile 
</path/to/file/with/message/to/sign> 

■ -f| — file  </path/to/file/for/signed/message> 

■ -k  | — key  </path/to/private/key/file> 

■ -p  | — codephrase  <private  code  phrase> 
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PGPMessageVerify 

Misconfiguration  Parallels  H-Sphere  PGP  message  verify. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPMessageVerify 

■ f| — messagefile  </path/to/file/for/signed/message> 

■ k | — key  </path/to/public/key/file> 


RepostResellerSSLConfigs 

NAME: 

psoft. hsphere.tools. RepostResellerSSLConfigs  This  Parallels  H-Sphere  tool  recreates 
virtual  host  config  files  for  resellers. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . RepostResellerSSLConfigs 
[options] 

OPTIONS: 

■ help  - shows  this  screen 

■ process  - run  the  tool  for  all  config  files 

■ reseller  <res  name  1>  <res  name  2>...<res  name  n>  - run  the  tool  for 
determined  reseller  user  names. 


66 


Control  Panel  Server 


ServiceZoneRenamer 

Utility  for  changing  service  zone  name.  Changes  zone  name,  LServers  names,  rebuilds 
DNS. 

WARNING:  USE  ONLY  ON  EMPTY  INSTALLATION  OF  H-SPHERE. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . ServiceZoneRenamer  -oz 
zone_name  -nz 

zone_name 

■ -oz  | — oid_zone  Name  of  the  currently  present  service  zone 

■ -nz  | — new  zone  Name  which  should  be  set  to  service  zone 


BillingEraser 

Permanently  erases  billing  history  of  accounts.  Before  running  this  utility,  stop  Parallels 
H-Sphere  and  back  up  Parallels  H-Sphere  system  database. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . BillingEraser— accounts 
list_of_account_ids— resellers  list_of_reseller_ids 

NOTE: 


■ When  — resellers  option  is  used,  the  utility  erases  billing  history  for  the  specified 
reseller  and  all  his  users. 

■ There  is  no  possibility  to  do  it  only  for  a reseller  account  (without  touching  users). 

■ Using — accounts  and — resellers  parameters  simultaneously  is  disabled. 

■ Specified  accounts  and  reseller  ids  are  delimited  with  commas. 
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SetQuota 

NAME: 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. SetQuota 

This  Parallels  H-Sphere  tool  resets  quota  on  a web  box  according  to  the  data  found  in 
Parallels  H-Sphere  DB  for  each  account  located  on  each  logical  server. 

SYNOPSIS: 


psof t . hsphere . tools . SetQuota  [options] 

OPTIONS: 


■ help  - shows  help 

■ lid  | — lserverid  - process  accounts  located  on  Logical  Server  with  specified  ID 
only 


UrchinReconfig 

NAME: 

psof t . hsphere . tools  .UrchinReconfig  - Regenerate  Urchin  config.  Used,  for 
example,  after  account  migration  to  restore  Urchin  settings  for  moved  domains. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . UrchinReconfig  [options] 

OPTIONS: 

■ help  - shows  help 

■ a | — accounts  - list  of  account  IDs  delimited  with  or  ‘all’  for  all  accounts 

■ s | — servers  - list  of  logical  server  IDs  delimited  with  7,  or  ‘all’  for  all  servers 

SAMPLE: 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. UrchinReconfig  -a  ‘1002,8383,1237’  -s 
‘12,35,37’ 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. UrchinReconfig  -a  all  -s  all 
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OffLogs 

■ bash-2. 05b$  java  -Xms64M  -Xmx51 2M  psoft.hsphere. tools. OffLogs — help 


NAME: 

psoft.hsphere.tools. OffLogs  - Regenerate  users’  logs  and  stats  config 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  [options] 

OPTIONS: 

■ — help  - shows  this  screen 

■ -a  | — accounts  list  of  account  IDs,  or  all  for  ‘all’  accounts, 

■ - delimiter  -s  | — servers  list  of  logical  server  IDs,  or  ‘all’  for  all  servers,  7 

■ - delimiter  -e  | — erroriog  re-generate  errorlog  only 

■ -ag  | — agentiog  re-generate  agentlog  only 

■ _r  | — referreriog  re-generate  referrerlog  only 

■ -t  | — transf eriog  re-generate  transferlog  only 

■ -w  | — webalizer  re-generate  webalizer  only 

■ -m  | — modiogan  re-generate  modlogan  only 

■ -aw  | — awstats  re-generate  awstats  only 

SAMPLE: 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. OffLogs  -a  ‘1002,8383,1237’  -s 
‘12,35,37’ 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. OffLogs  -a  all  -s  all 
java  -Xms64M  -Xmx512M  psoft. hsphere. tools. OffLogs  -s  24  -aw  -w 
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Reset  Balance 

NAME: 

psoft.hsphere.tools.ResetBalance 

This  Parallels  H-Sphere  tool  resets  billing  balance  using  different  criteria.  By  default, 
the  tool  runs  only  in  information  mode. To  fix  balances,  run  utility  with — process 
option. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . ResetBalance  options 

OPTIONS: 

■ h | — help  - shows  this  screen 

■ acc  | — acountid  number  - process  only  accounts  with  given  number 

■ ail  | — all  - process  all  accounts 

■ b | — balance  <id  baiance>  - process  accounts  with  balance  equal  to  cbalance 
for  process> 

■ n | — newbaiance  <new  baiance>  - set  balance  to  cbalance  for  process> 

■ d | --description  - Ccredit  description>  - notes  which  will  be  added  to 
credit  operation 

■ process  - to  force  process,  otherwise  only  affected  accounts  will  show 
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RegeneratelpsFile 

NAME: 

psoft.hsphere.tools.  RegeneratelpsFile 

This  Parallels  H-Sphere  tool  regenerates  file  /hsphere/iocai/network/ips  on 
Unix  physical  box 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . RegeneratelpsFile  options 

OPTIONS: 

■ — help  - shows  this  screen 

■ -all  - regenerate  on  all  physical  boxes 

■ -pid  - regenerate  on  physical  servers  with  specified  IDs 


LicenseExtractor 

A tool  to  import  License  info  to  a file  or  print  it  to  console  screen. 

NAME: 

psoft . hsphere .tools. LicenseExtractor 

Imports  License  info  to  a file  or  prints  it  to  console  screen. 

SYNOPSIS: 


java  psoft . hsphere . tools . LicenseExtractor  [options] 

OPTIONS: 

■ help  - shows  this  screen 

■ file  </path/to/f ile> 

</path/ to/f  iie>  - absolute  path  to  the  file  and  file  name  where  license  info  will  be 
imported; 

without  options  - shows  license  info  to  console  screen. 
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MailRelayCorrector 

If  you’ve  updated  Parallels  H-Sphere  to  3.1  Beta  1 , run  this  tool  to  create  virtual  users 
for  every  mail  resource:  mailbox,  alias,  forward,  autoresponder,  mailing  list,  and  mail 
sms  if  mail  relay  is  enabled  for  mail  domain. 

NAME: 

psof t . h sphere .tools . MailRelayCorrector 

Processes  all  mail  resources  (mailbox,  forward,  alias,  autoresponder,  mailing  list,  sms) 
for  maildomains  with  enabled  mail  relays  and  creates  vitrtual  users  for  each  of  them. 

USAGE  EXAMPLES: 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. MailRelayCorrector  -a  1233,1254 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. MailRelayCorrector  -lid  7 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. MailRelayCorrector  -d 
my_maildomain.com 

java  -Xms64M  -Xmx512M  psoft.hsphere.tools. MailRelayCorrector — all 

OPTIONS: 

■ -h  | — help  - shows  this  screen 

■ — all  or  without  any  parameter  - process  all  accounts 

■ -a  | — accounts  - process  accounts’  IDs  separated  by  comma 

■ -lid  | — lserverid  - process  accounts  on  logical  server  with  given  number 

■ -d  | — domains  - process  domains  separated  by  comma 
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Securing  Your  CP  Server  with  SSL 

This  document  gives  a step-by-step  instruction  on  how  to  secure  your  CP  apache 
server  with  a regular  SSL  certificate. 

Note:  You  can  secure  your  control  panel  with  a wildcard  certificate  if  you  install  it  on 
the  same  domain  name.  For  example,  if  your  cp  domain  name  is  cp . example . com, 
you  can  secure  it  by  installing  wildcard  certificate  to  example . com. 

We  recommend  that  you  configure  your  system  to  be  accessible  both  by  http  and  https, 
because  Parallels  SiteStudio  does  not  fully  support  https  protocol. 

> To  secure  your  CP  with  regular  SSL: 

1.  Create  or  choose  a directory  to  store  SSL-related  files.  E.g.: 

#mkdir  cert 

Make  this  directory  available  only  for  root: 

#chmod  700  cert 
Go  to  this  directory: 

#cd  cert 

2.  Generate  an  SSL  private  key  with  the  OpenSSL  utility: 

#openssl  genrsa  -des3  -out  server. key  2048 

When  prompted  for  a pern  phrase,  enter  any  combination  of  4 characters,  e.g. 

1 234.  A unique  private  key  will  be  generated  into  the  server . key  file. 

For  more,  read  modssl  documentation  (http://www.modssl.org/source/mod  ssl- 
2.8.1 6-1 -3.29.tar.az). 

3.  Copy  this  file  to  a secure  location.  You  will  need  it  later. 

4.  Make  the  newly  generated  file  readable  only  by  root: 

#chmod  600  server. key 

5.  To  view  the  content  of  the  private  key  file,  use  the  command: 

#openssl  rsa  -noout  -text  -in  server. key 

6.  Remove  pass  phrase  from  the  private  key: 

#openssl  rsa  -in  server. key  -out  server . key . unsecure 

7.  Now  you  don’t  need  the  private  key  with  the  pass  phrase  any  more. 
Overwrite  it  with  the  private  key  without  the  pass  phrase: 

#cp  server . key . unsecure  server. key 

8.  Generate  an  SSL  certificate  signing  request  based  on  the  private  key: 

#openssl  req  -new  -key  server. key  -out  server. csr 

You  will  have  to  answer  many  questions  related  to  your  company.  Your  answers 
are  required  to  be  included  in  the  certificate. 

Note:  Common  name  is  the  URL  at  which  you  want  your  control  panel  to  be 
available,  e.g.  cp . yourdomain . com  (not  yourdomain  . com). 

9.  Check  the  content  of  the  certificate  request  file: 

#openssl  req  -noout  -text  -in  server. csr 
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If  you  find  a mistake  in  the  data  you  have  submitted,  you  can  re-generate  the 
request  anew. 

10. Make  sure  to  back  up  your  SSL  files: 

# mkdir  backup 

# chmod  700  backup 

# cp  ./*.*  backup/ 

11. Send  the  generated  CSR  file  to  a trusted  Certificate  Authority  for 
signing.  They  will  send  you  back  the  certificate.  Save  it  as  server. crt. 

12. To  view  the  content  of  the  certificate,  run: 

# openssl  x509  -noout  -text  -in  server. crt 

13. Save  the  private  key  and  the  certificate: 

# cp  -f  ./server. key 

/hsphere/ local/home/ cpanel/ apache/e tc/ssl . key/ 

# cp  -f  ./server. crt 

/hsphere/local/home/cpanel/apache/etc/ssl . crt/ 

14. Important:  Make  sure  to  back  up  the  ssl.key  and  ssl.crt  files  to  a safe 
location.  You  may  need  them  in  the  future. 

15. If  your  certificate  was  signed  by  a non-trusted  certificate  authority,  run 
the  following  command: 

# cp  -f  . /ca-bundle . crt 

/hsphere/local/home/cpanel/apache/etc/ssl . crt/ 

16. If  your  certificate  doesn’t  require  chain  certificate,  skip  this  item. 
Otherwise,  do  the  following: 

a Store  chain  certificate  in  file: 

/hsphere /local /home/ cpanel/ apache /etc/ ssl . crt/ca . crt 

b Create  custom  CP  apache  config  template  if  you  do  not  have  any  (see 
Appendix  C of  Parallels  H-SPhere  Installation  Guide) 

c Add  line  (according  to  Step  2 “Edit  template”  in  the  above  mentioned 
document): 

SSLCertif icateChainFile 

/hsphere /local /home/ cpanel/ apache /etc/ ssl . crt/ca . crt 

to  file: 

/hsphere/ local /home/ cpanel/ apache /etc/httpd . conf . tmpl . custom 
17. Open  the  file  hsphere  . properties: 

# vi 

/hsphere/local/home/cpanel/ shiva/psof t_conf ig/hsphere .propert 
ies 

and  change  lines: 

CP_PORT  = 8080 
CP_PROTOCOL=http : / / 

to: 

CP_PORT  = 8443 
CP_PROTOCOL=https  : / / 

18.  Restart  Parallels  H-Sphere  (on  page  41). 

19.  Check  the  log  file: 

# vi  /hsphere/local/home/cpanel/apache/logs/ssl_engine_log 
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Now  your  control  panel  must  be  available  at  both 

http : / / cp . yourdomain . com: 8080  and  https : / / cp . yourdomain . com: 8443 


In  this  section: 


Disabling  HTTP  Access 74 

Switching  Between  IP  and  Domain  Name 75 


Disabling  HTTP  Access 

We  don’t  recommend  disabling  HTTP  access,  because  it  is  required  by  Parallels 
SiteStudio.  Still,  if  you  have  chosen  to  disable  http,  do  the  following: 

1.  Open  the  file  ~cpanel/apache/etc/httpd.  conf 

2.  If  you  would  like  to  exclude  http  access  and  use  only  secure 
connections,  comment  out  the  line  “Listen  8080”  in  the  block 

IfDefine  SSL. 

3.  Restart  Parallels  H-Sphere  (on  page  41). 
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Switching  Between  IP  and  Domain  Name 

You  cannot  have  your  control  panel  available  both  by  domain  name  and  IP  address. 
You  can  have  only  one. 

> To  switch  between  IP  and  domain  name  control  panel  access: 

1.  Open  the 

/hsphere/ local /home/ cpanel / shiva/ psof t_conf ig/hsphere 
.properties  file. 

2.  Set  the  value  of  cp_host  to  your  new  cp  url/ip.  Make  sure  not  to 
change  the  value  of  the  path_site_studio  property. 

3.  Save  and  exit  the  file. 

4.  Restart  Parallels  H-Sphere  (on  page  41). 

Check  for  feedback  from  Parallels  H-Sphere  owners  on  how  to  use  Parallels  H-Sphere 
with  POP3  SSL,  IMAP  SSL,  SMTP  SSL  and  SFTP: 
http://forum.psoft.net/showthread.php?threadid=3187. 


Upgrading  Java 

This  section  explains  how  to  upgrade  Java  SDK  on  the  Parallels  H-Sphere  control 
panel  server. 

In  this  section: 


Supported  Versions 75 

Upgrade  Procedure 76 


Supported  Versions 

Linux 

It  is  recommended  that  Linux  owners  use  the  Java  SDK  1 .4.2  by  Sun  Microsystems 
(http://iava.sun.eom/j2se/1 .4.2/).  This  applies  to  all  products  in  the  RedHat  Linux 
product  line. 

FreeBSD 

Java  1 .4.2  is  implemented  on  CP  server  under  FreeBSD  4.x.  Please  update  your 
Parallels  H-Sphere  to  the  latest  version  where  you  can  update  Java  to  1 .4.2. 
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Upgrade  Procedure 

You  have  two  alternative  ways  to  upgrade  Java.  Choose  one  of  the  alternatives  below. 

In  this  section: 


Automatically  By  Means  of  Parallels  H-Sphere  Update  Script 76 

Manually  from  Java  1 .4.2  SDK  by  Sun  Microsystems  (Linux  Only) 77 


Automatically  By  Means  of  Parallels  H-Sphere  Update  Script 

> To  upgrade  Java  automatically: 

1.  Log  into  the  CP  server  as  root: 

# su  - 

2.  Download  the  upgrade  package  for  your  Parallels  H-Sphere  version 
from  http://download.hsphere.parallels.com,  untar  it  and  execute. 

3.  In  the  upgrade  script  interface,  type  the  following  option  to  update  Java 
to  1.4.2: 

javaupdate 

This  will  update  your  Java  to  1 .4.2  and  will  also  update  your  Parallels  H-Sphere  Java 
classes. 
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Manually  from  Java  1.4.2  SDK  by  Sun  Microsystems  (Linux 
Only) 

> To  upgrade  Java  manually: 

1.  Log  into  the  CP  server  as  root: 

# su  - 

2.  Stop  Parallels  H-Sphere: 

# /etc/rc.d/init.d/httpdcp  stop 

3.  Stop  all  java  processes  on  your  system: 

# killall  java 

4.  Set  up  Java  JDK  1 .4.2  following  the  instructions  by  Sun  Microsystems 
(http://iava.sun.eom/i2se/1 .4.2/install-linux.html). 

5.  Update  symlink  /usr/ j ava/ j dk/  to  point  to  your  installation,  for 
example  to  /usr/ j ava/ j dkl  . 4 . 2_06. 

If  you  don’t  have  the  /usr/java/jdk/  symlink: 

1 . Create  it  to  point  to  your  installation. 

2.  In  the  file 

/hsphe re /local /home/ cpanel /apache/ etc/ j serv/ j serv . propertie 

s,  set  the  following: 

wrapper ,bin=/usr/j  ava/ jdk/bin/j  ava 

wrapper . classpath=/ usr/ j ava/ j dk/ j re/lib/rt . j ar 

6.  Skip  this  step  if  you  don’t  run  Parallels  SiteStudio. 

Open  the  file  /hsphere/ shared/ SiteStudio/imaker . sh  and  check  if  it  has 
the  line: 

JAVA_H0ME= ' su  -1  cpanel  -c  'echo  $JAVA_H0ME' ' 

If  it  doesn’t,  update  the  JAVA_HOME  parameter  in  this  file,  e.g.: 

JAVA  H0ME=/usr/ j ava/ j dkl . 4 . 2 

7.  To  ensure  correct  work  with  OpenSRS,  download  the  “Unlimited 
Strength”  Jurisdiction  Policy  Files  from 

http://iava.sun.com/products/ice/index-1 4.html#UnlimitedDownload.  The 

files  for  version  1 .4.2  can  be  downloaded  from  page 
http://iava.sun.eom/i2se/1 .4.2/download. html#docs,  section  “Other 
Downloads”.  Put  the  files  in  the  directory 

java_home / j re /lib /security  where  java_home  is  the  Java  SDK 
home  directory. 

8.  Upgrade  to  one  of  the  latest  versions  of  Parallels  H-Sphere. 

9.  Start  Parallels  H-Sphere: 

# /etc/rc.d/init.d/httpdcp  start 
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Converting  Parallels  H-Sphere  System 
Database  from  MS  SQL  to  PgSQL 

PgSQL  is  the  only  supported  format  for  the  Parallels  H-Sphere  system  database.  The 
conversion  procedure  suggested  in  this  section  takes  two  steps  listed  below. 


In  this  section: 


Step  1 . Convert  Database  from  MSSQL  Server  to  MySQL 78 

Step  2.  Convert  Database  from  MySQL  Server  to  PgSQL 79 


Step  1 . Convert  Database  from  MSSQL  Server  to 
MySQL 

> To  Convert  database  from  MSSQL  to  MySQL: 

1.  Rename  the  following  fields: 

■ table  esc_  rules:  rename  interval  to  interval2 

■ table  revenue:  rename  usage  to  usage2 

This  must  be  done  to  avoid  conflicts  in  MySQL,  and  must  be  changed  back  in  the 
MySQL  dump. 

2.  Download  the  mssql2mysql . exe  convertor  from 
http://download.hsphere.parallels.com/shiv/db  convert/mssql2mysql.ex 

e 

3.  Start  ms sql2mysql . exe  and  configure  setting  for  MSSQL/MySQL 
servers  (hosts,  usernames,  passwords,  new  database  name  for  mysql) 
and  save  settings. 

If  you  get  warnings  about  missing  componenets,  download  and  run  the 
MtaEdt22.exe  utility  from 

http://download.hsphere.parallels.com/shiv/db  convert/MtaEdt22.exe.  It  will 

download  and  set  up  all  missing  components. 

4.  Click  Connect  to  connect  to  mssql  database  and  select  the  database 
to  convert. 

5.  Select  all  necessary  tables  or  press  Select  ah  to  select  all  tables 

6.  Click  start  to  start  database  conversion 

7.  To  see  the  database  after  the  conversion: 

mysql  hsphere  mysql  (for  example) 
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Step  2.  Convert  Database  from  MySQL  Server  to  PgSQL 

Execute  all  suggested  queries  in  one  transaction.  Replace  PG_HOST_NAME  with  the 
name  of  the  host  where  PgSQL  server  is  running,  like  example . com. 

1.  Download  the  mysql/pgsql  dump  convertor  archive  from 
http://download.hsphere.parallels.com/shiv/db  convert/my2pq.tqz  and 

unpack  it: 

tar  zxvf  my2pg . tgz 

2.  Dump  tables  and  data  from  mysql: 

mysqldump . exe  hsphere_mysql  > hsphere_dump 

3.  As  the  result,  you  will  get  a MySQL  dump  with  table  structure  and  data 
(hsphere_dump) 

4.  In  MySQL  dump,  rename  the  following  fields: 

■ table  esc_  rules:  rename  interval2  to  interval 

■ table  revenue:  rename  usage2  to  usage 

5.  Convert  mysql  dump  to  pgsql  dump: 

my2pg.pl  hsphere_dump  > hsphere^pgsql 

As  the  result,  you  will  get  a converted  dump  (hsphere_pgsql) 

6.  Replace  timestamp  to  timestamp  with  time  zone. 

7.  If  the  database  already  exists,  delete  it: 

dropdb  -h  P G_HO S T_NAME  -U  wwwuser  hspherejogsql 

8.  Create  a new  (empty)  database: 

createdb  -h  P G_HO S T_NAME  -U  wwwuser  hspherejogsql 

9.  Restore  the  database  from  dump  (tables  and  data): 

psql  -h  P G_HO S T_NAME  -d  hspherejogsql  -U  wwwuser  -f 
hsphere_pgsql  > migrate_errors 

• d - database  name 
-f  - file  with  dump 

As  a result,  you  will  see  convertion  results  in  the  migrate_errors  file. 

10.  Connect  to  the  database  and  check  all  tables  and  data: 

psql  -h  P G_HO S T_NAME  -d  hsphere^pgsql  -U  wwwuser 

11.  For  each  record  of  the  sequences  table,  run  the  following  two 
commands  against  the  Postgres  DB: 

CREATE  SEQUENCE  "<seq_name>"  start  <id>; 

SELECT  nextval  ( '<seq_name>' ) ; 

For  example,  for  the  record  newid  ->  27  64  88,  execute  the  following  SQL 
statements: 

CREATE  SEQUENCE  "newid"  start  276488; 

SELECT  nextval  ( 'newid' ) ; 
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Converting  Parallels  H-Sphere  Database 
To  UNICODE 

The  system  database  must  be  in  UNICODE  (UTF-8). 

> To  convert  your  database  to  Unicode: 

1.  Stop  the  control  panel 

Log  in  as  root  and  stop  the  control  panel: 

For  Linux: 

/etc/rc.d/init.d/httpdcp  stop 
killall  -9  java 

For  FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
killall  -9  java 

2.  Find  out  your  current  database  encoding 
Type: 

su  -1  cpanel  -c  'psql  hsphere' 
hsphere#  \encoding 

If  the  encoding  is  UNICODE  (UTP-8),  you  have  found  what  you  need.  If  not,  the 
next  step  is  to  dump  Parallels  Pi-Sphere  system  database. 

3.  Dump  Parallels  H-Sphere  system  database 

1 . Create  and  enter  backup  directory: 
mkdir  pg_backup 

cd  pg_backup 

2.  Get  the  password  for  wwwuser.  You’ll  need  it  to  query  the  database: 

cat  ~cpanel/shiva/psoft_config/hsphere. properties  | grep  PASS 

3.  Dump  Parallels  Pi-Sphere  system  database. 

Export  schema: 

pg  dump  -u  -s  -f  schema. db  hsphere 

chmod  600  schema. db 

cp  -p  schema. db  schema  backup. db 

Export  data: 

pg  dump  -u  -a  -f  data . db  hsphere 

chmod  600  data.db 

cp  -p  data.db  data_backup . db 

Notes: 

1 . If  your  system  database  is  large,  the  dump  can  take  several  hours  to 
complete.  You  can  speed  it  up  by  setting 

f sync=of f 

in  postgresqi . conf . When  you  are  done,  unset  this  option  back  for  safety 
reasons. 
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2.  The  dump  file  is  created  with  644  permissions  by  default;  you  need  to  set 
more  secure  600  permissions  to  prevent  the  data  from  being  read  by  other 
users. 

4.  For  additional  security,  you  may  disallow  access  to  the  backup  directory  for  all 
other  users: 
chmod  700 

4.  Convert  the  dump  to  UNICODE. 

Convert  the  dump  into  Unicode  with  the  iconv  utility. 

Linux: 

iconv— from-cod e=<REGIONAL_ENCODING>  -~to-code=UTF-8  -o 
utf_data.db  data.db 
mv  utf  data.db  data.db 

FreeBSD: 

iconv  -f  <REGIONAL_ENCODING>  -t  UTF-8  data.db  > utf  data.db 
mv  utf  data.db  data.db 

If  your  dump  file  exceeds  2GB: 

1 . Split  it  into  smaller  files,  1GB  each: 
split  -b  1024m  data.db  data  db 

2.  Run  iconvf  or  for  each  of  these  files  to  convert  them  to  UNICODE: 

iconv— f rom-code=</?EG/ON4L_EWCOD/WG>--to-code=UTF-8  -o 
utf_data_db . aa  data_db.aa 

i co nv— f r om- code=<REGI ONAL_ENCODING> — to-code=UTF-8  -o 
utf_data_db . ab  data_db.ab 

3.  Join  them  back  into  data.db: 

cat  utf_data_db . aa  utf_data_db . ab  utf_data_db . ac  ...  > 
data . db 

Here,  <REGIONAL_ENCODING>  is  the  source  encoding.  For  example,  for  native 
US  English  encoding: 

Linux: 

iconv— f rom-code=ISO-8859-l  --to-code=UTF-8  -o  utf  data.db 
data . db 

FreeBSD: 

iconv  -f  ISO-8859-1  -t  UTF-8  data.db  > utf  data.db 

The  resulting  data . db  file  will  contain  the  data  converted  to  Unicode. 

For  better  security,  run  the  following  command: 
chmod  600  data.db 

5.  Save  the  postgres  directory  in  a backup  location. 

1 . Stop  the  database: 

For  Linux: 

/etc/rc.d/init.d/postgresql  stop 
For  FreeBSD: 

/usr/local/etc/rc. d/010 .pgsql . sh  stop 

2.  Save  the  postgres  directory: 

For  Linux: 
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cp  -pR  ~postgres/data  ./ 

For  FreeBSD: 

cp  -pR  ~pgsql/data  ./ 

3.  Start  the  database: 

For  Linux: 

/ etc/ rc . d/ init . d/postgresql  start 
For  FreeBSD: 

/usr/local/etc/rc. d/010 .pgsql . sh  start 

6.  Recreate  Parallels  H-Sphere  database. 

1 . Delete  old  Parallels  Fl-Sphere  database: 

# su  -1  cpanel 

$ dropdb  hsphere 

2.  Create  database: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 

3.  Create  Parallels  Fl-Sphere  DB  schema: 

psql  -q  -U  wwwuser  -f  schema. db  hsphere 

4.  Import  Parallels  Fl-Sphere  system  data: 

psql  -q  -U  wwwuser  -f  data.db  hsphere 

Note:  If  you  face  problems  with  importing  data,  please  see  the  Troubleshooting 
(on  page  82)  section  in  CP  Acceleration  guide. 

5.  If  you  added 

f sync=of f 

to  postgresql.conf,  don’t  forget  to  delete  it. 

6.  Start  the  Control  Panel  (on  page  41). 


Accelerating  Control  Panel 

When  your  Control  Panel  is  slow  or  you  have  high  CPU/memory  load,  you  can  do  a 
few  steps  to  accelerate  its  performance. 


In  this  section: 


Parallels  Fl-Sphere  Java-related  Issues 82 

Optimizing  Parallels  Fl-Sphere  System  Database 83 

Troubleshooting 89 


Parallels  H-Sphere  Java-related  Issues 

1.  Tomcat  Optimization 

Customize  Tomcat  environment  variables  (on  page  54). 


Control  Panel  Server 


83 


Optimizing  Parallels  H-Sphere  System  Database 

To  optimize  the  system  database,  perform  operations  listed  in  this  section. 

In  this  section: 

Converting  Bigint  to  Int4 84 

Updating  Moddb 85 

Performing  VACUUM 86 

Optimizing  Postgres 87 
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Converting  Bigint  to  Int4 

Skip  this  procedure  if  you  have  have  already  performed  it  or  if  you  have  PostgreSQL  8 
or  a later  version. 

Postgres  migration  from  int8  to  int4  is  very  effective  if  you  host  more  than  500 
accounts.  By  default,  Postgres  7 can’t  index  fields  of  the  int8  type. 

You  need  to  perform  it  once  at  any  time. 

For  this  procedure,  find  the  partition  with  sufficient  amount  of  free  space. 

1 . Stop  the  Control  Panel  (check  hsphere . log  that  no  crons  are  running) 

2.  Export  schema: 

pg  dump  -u  -s  -f  db  old.db  hsphere 
chmod  600  db  old.db 
cp  db  old.db  db . db 

Note:  dump  file  is  created  with  644  permissions  by  default;  you  need  to  set  more 
secure  600  permissions  to  prevent  the  data  from  being  read  by  other  users. 

3.  Convert  int8  to  int4: 

vi  db . db 

In  vi  editor,  change  every  instance  of  bigint  and  int8  to  int4  by  typing  the  following 
commands: 

%s /bigint /int 4 /g 
%s/int8/int4/g 

4.  Then,  still  editing  db . db  in  vi,  change  type  back  to  int8  for  the  ip_num 
column  in  the  l_server_ips  table  and  its  index. 

a find  the  ip_num  definition  in  the  create  table  "i_server_ips"  ( ... 

) ; command: 
ip_num  int4  NOT  NULL 

• and  change  int 4 to  int8; 
b find  the  index  creation  command: 

CREATE  INDEX  "1  server  ips  numkey"  on  "1  server  ips"  using 
btree  ( "ip_num"  "int4_ops"  ) ; 

• and  change  int4_ops  to  int8_ops. 

5.  Export  Data: 

pg  dump  -u  -a  -f  data . db  hsphere 
chmod  600  data.db 

Note:  dump  file  is  created  with  the  644  permissions  by  default;  you  need  to  set 
more  secure  600  permissions  to  prevent  the  data  from  being  read  by  other  users. 

6.  Recreate  DB: 

dropdb  -U  wwwuser  hsphere 
createdb  -U  wwwuser  hsphere 

7.  Create  Schema: 

psql  -q  -U  wwwuser  -f  db.db  hsphere 

8.  Import  Data: 

psql  -q  -U  wwwuser  -f  data.db  hsphere 


Control  Panel  Server 


85 


9.  Start  the  Control  Panel. 


Updating  Moddb 

Note:  Prior  to  running  moddb,  update  your  Parallels  H-Sphere  to  the  latest  version. 

Moddb  is  one  of  the  scripts  included  in  the  Parallels  H-Sphere  update.  However,  it  is 
not  automatically  performed  during  the  Parallels  H-Sphere  installation.  You  should 
launch  it  manually  and  only  once.  To  do  this: 

1.  Stop  the  Control  Panel. 

2.  Make  moddb: 

1 . Download  the  Parallels  H-Sphere  update  (to  the  installed  version) 

2.  Run  the  update  script.  For  example,  for  the  Parallels  H-Sphere  2.3.2  Patch  5 
update  script: 

#sh  ./U23.2P5 

3.  Choose  the  moddb  option. 

This  option  will  back  up  old  Parallels  H-Sphere  database  and  modify  Parallels 
H-Sphere  DB  scheme  (increase  some  fields  length,  e.g:  email,  notes, 
suspend/resume  reason  etc.). 

Note:  You  may  be  prompted  for  your  Parallels  H-Sphere  DB  password  under 
Postgres  versions  starting  from  7.2.x.  Enter  the  password  to  complete  the 
procedure. 


3.  Start  the  Control  Panel. 
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Performing  VACUUM 

VACUUM  should  be  performed  regularly  (e.g.,  once  a week).  You  may  put  the 
corresponding  script  into  cron. 

Mind,  however,  that  this  procedure  requires  a lot  of  system  resources  and  creates  a 
high  server  load. 

We  recommend  you  to  back  up  the  database  before  performing  vacuumdb.  Be  careful: 
if  the  server  gets  down  during  this  process,  some  data  may  be  lost! 

To  backup  your  system  database,  run  the  hs_bck  script: 

/hsphere/shared/ scripts/cron/hs_bck , 

or 

cd  /hsphere/shared/backup 
. /hs_bck  hs_bck . cf g 

Do  the  following  procedure  to  apply  VACUUM  to  your  system: 

1.  Log  into  the  server  as  root: 

su  - postgres 
for  FreeBSD: 
su  - pgsql 

2.  Connect  to  the  database: 

psql  -U  wwwuser  -d  hsphere 

3.  Do  vacuum: 

hsphere$  vacuum  full; 
or 

vacuum  analyze; 
or 

vacuum; 

depending  on  the  PostgreSQL  server  version 

Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete! 
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Optimizing  Postgres 

You  can  enhance  CP  productivity  by  optimizing  some  Postgres  parameters  in  the 
postgresqi . conf  file.  Default  values  of  these  parameters  are  intended  for  less 
powerful  workstations,  and  therefore  these  values  should  be  significantly  increased  for 
better  performance  on  servers  with  multiple  CPUs,  large  RAM,  and  with  large  and 
intensively  used  databases. 

Consider  reconfiguration  of  the  following  parameters  (please  refer  to  PostgreSQL 
documentation,  http://www.postqresql.Org/docs/7.4/interactive/runtime-confiq.html,  for 
details): 

■ shared_buf  f ers  - size  of  shared  buffers  for  the  use  of  Postgres  server 
processes.  It  is  measured  in  disk  pages,  which  are  normally  8kB.  Default  value  is 
64,  i.e.,  512  kB  RAM.  We  recommend  increasing  this  parameter: 

■ for  middle-size  database  and  256-512  MB  available  RAM:  to  16-32  MB  (2048- 
4096) 

■ for  large  database  and  1 -4  GB  available  RAM:  to  64-256  MB  (81 92-32768) 

■ sort_mem  - size  of  RAM  allocated  for  sorting  query  results.  Measure  unit  is  IkB. 
Default  value  is  1024.  We  recommend  setting  this  parameter  to  2-4%  of  available 
RAM. 

■ waijouf  fers  - size  of  the  transaction  log  buffer.  Measure  unit  is  8kB.  Default 
value  is  8.  It  can  be  increased  to  256-512  for  better  processing  of  complex 
transactions. 

■ max_connections  - the  maximum  number  of  connections  to  a database  at  a time. 
Default  value  is  32.  We  recommend  increasing  it  to  at  least  64. 

■ checkpoint_segments  - maximum  distance  between  automatic  WAL  (Write- 
Ahead  Log)  checkpoints.  Measured  in  log  file  segments  (each  segment  is  normally 
16  megabytes).  Default  value  is  3.  We  recommend  increasing  this  parameter  if  data 
is  being  actively  accessed  and  modified. 

■ checkpoint_timeout  - maximum  time  for  transaction,  in  seconds.  Default  value 
is  3000.  We  recommend  increasing  this  parameter  at  least  10  times. 

■ ef  f ective_cache_size  - sets  the  optimizer’s  assumption  about  the  effective 
size  of  the  disk  cache.  Measure  unit  is  8kB.  Default  value  is  1 000.  If  you  have 
enough  memory,  we  recommend  setting  this  parameter  to  25-50%  of  available 
RAM. 

WARNING:  For  FreeBSD,  kernel  recompilation  is  required  before  changing  memory 
usage  parameters  in  postgresqi. conf!  Read  Managing  Kernel  Resources, 
http://www.postqresql.orq/docs/7.4/interactive/kernel-resources.html,  in  PostgreSQL 
documentation. 


> To  reconfigure  Postgres  parameters: 

1.  Stop  Postgres. 

2.  Modify  the  ~postgres/data/postgresql . conf  file  (in  Parallels  H- 
Sphere  2.5  and  up,  modify  its  custom  template  as  described  in 
Appendix  C of  Parallels  H-Sphere  Installation  Guide). 

Here  is  an  example  of  PostgreSQL  configuration  for  a server  with  4 CPUs,  4GB 
RAM,  with  2.5  GB  database  dump  and  a separate  hard  drive  allocated  for 
transaction  logs: 
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sort  mem  = 131072 

shared  buffers  = 262144 

max  connections  = 64 

wal  buffers=1000 

checkpoint  segments  = 9 

checkpoint  timeout  = 3600 

ef f ective_cache_size  = 100000 

3.  Start  Postgres  and  make  sure  it’s  working  properly.  If  parameters  are 
incorrect,  Postgres  might  not  start.  In  this  case,  please  also  set  the 
SHMALL  and  SHMMAX  kernel  parameters  according  to  the  rules 
described  in  the  RedHat  documentation. 

4.  Start  Postgres. 
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Moving  Transaction  Logs  to  a Separate  Hard  Drive 

If  the  system  database  is  large  (more  than  1G),  we  recommend  allocating  a separate 
hard  drive  for  its  transaction  logs.  It  is  especially  helpful  for  the  database  migration  or 
recovery  (on  page  332). 

> To  move  transaction  logs  to  another  hard  drive: 

1.  Stop  Postgres. 

2.  Mount  a new  hard  drive. 

3.  Move  the  data/pg_xlog  directory  from  the  PostgreSQL  home 
directory  to  the  new  disk. 

4.  Create  the  data/pg_xlog  symlink  to  the  new  location  in  place  of 
the  moved  directory. 

5.  Start  Postgres. 
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Troubleshooting 

Sometimes  while  importing  data  you  may  get  the  message  like  this: 

psql:data.db:5271 1 1 : ERROR:  copy:  line  422025,  Bad  float8  input  format — underflow 
psql:data.db:5271 1 1 : PQendcopy:  resetting  connection 

This  means  that  Postgres  cannot  interpret  data  it  has  just  exported. 

You  need  to  open  the  data.db  file: 

vi  data.db 

and  remove  the  line  which  number  is  calculated  in  the  example  above  as 
N=527iii+422025.  This  line  would  contain  a float8  number  like  1 .2e-318.  After 
removing  that  line,  you  need  to  recreate  and  reload  the  database. 


Changing  CP  URL 

This  section  tells  you  how  to  modify  the  URL  of  your  control  panel. 

In  this  section: 
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Changing  IP  Address  to  Domain  Name  in  CP  URL 

Sometimes,  mostly  when  you  have  just  installed  Parallels  H-Sphere,  you  receive  the 
following  error  while  trying  to  access  your  Control  Panel  by  domain  name: 

Control  Panel  Error 

You  have  entered  invalid  control  panel  location.  Please  enter  your  account  login  and 
password. 

In  this  case,  you  need  to  change  your  hostname  to  your  CP  domain  name  instead  of 
the  IP  address: 

1.  Log  into  your  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Edit  the  hsphere. properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 
In  the  cp_host  field,  enter  the  domain  name  instead  of  the  IP  address. 

Important:  If  you  changed  the  path_site_studio  variables  in 

~ cpanel/  shiva /pso  ft  con  fig/ hsphere  .properties  file  to  a domain 
name,  make  sure  to  change  IP  to  the  domain  name  in  all  SS  conf  files 

(/hsphere/  shared/ Si  te  Studio /pso  ft_con  fig/). 

3.  Restart  Parallels  H-Sphere  (on  page  41). 
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Changing  Parallels  H-Sphere  Port 

By  default,  Parallels  H-Sphere  is  configured  to  use  port  8080,  and  it  is  not 
recommended  to  use  other  ports.  However,  if  you  still  need  to  change  the  port: 

1.  Login  to  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Edit  ~ cpanel / shiva /p so f t_conf ig/h sphere .properties: 

CP_PORT  = <CUSTOM_CP_PORT> 

DEFAULT_CP_PORT  = <CUSTOM_CP_PORT> 

If  you  are  running  Parallels  SiteStudio,  also  update  this  line: 

PATH_SITE_STUDIO  = 

http://<CP  IP>:<CUSTOM  CP  PORT>/studio/servlet/psoft .masonry. 
Builder 

3.  Edit /hsphere/local/home/cpanel/apache/conf /httpd. conf 

as  described  in  Appendix  C of  Parallels  H-Sphere  Installation  Guide: 

Port  <CUSTOM_CP_PORT> 

4.  If  you  are  running  Parallels  SiteStudio,  update  all  Parallels  SiteStudio 
configuration  files  that  are  located  in 

/hsphere/ shared/ Si te Studio /p so ft_conf ig/. 
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Changing  Entire  CP  URL 

Control  Panel  runs  on  the  Tomcat  servlet  engine  (on  page  54)  and  therefore  CP  URL 
pathname  configuration  differs  from  that  of  JServ  (on  page  46)  in  prevous  versions. 

A typical  Parallels  H-Sphere  control  panel  URL  looks  similar  to 

http : / / example . com: 8080/psoft/ servlet/psoft . hsphere .CP/ 

where: 

■ example . com  is  the  domain  name, 

■ psof t/serviet  is  the  mount  point, 

■ psof t. hsphere. cp  is  the  servlet  name. 

1.  Login  to  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Edit  ~ cpanel/ shi va/p so ft_conf ig /hsphere .properties  to 

change  your  servlet  name  and  mount  point: 

# old  settings— commented  out 

# UPLOADER  URL  = /psoft/servlet/psoft . hsphere . Uploader 

# DOWNLOAD  URI  = /psoft/servlet/psoft . hsphere . Downloader 

# CP_URI  = /psoft/servlet/psoft . hsphere . CP 

# CLIENT_CP_URL  = psof t . hsphere . CP 

# new  settings 

UPLOADER  URL  = /cp/servlet/hsphere . Uploader 
DOWNLOAD  URI  = /cp/servlet/hsphere . Downloader 
CP  URI  = /cp/servlet/hsphere . CP 
CLIENT_CP_URL  = hsphere. CP 

Important:  To  avoid  problems,  please  check  that  the  same  servlet  name  and 
mount  point  are  set  in  all  these  parameters!  CP_URI  takes  the  precedence 
otherwise. 

3.  Logout  from  cpanel  back  to  root  and  run  the 

j akarta_serviet_upt . pi  script  to  apply  the  new  servlet  name  and 
mount  point  to  the  Tomcat  configuration  files  (on  page  54)  and  to  the 
index  page  template  ~cpanei/ shiva/ shiva- 
templates / index.html: 

cd  ~cpanel/shiva/psof t_config 
. / jakarta_servlet_upt .pi 

The  script  replaces  old  servlet  name  and  mount  point  in  the  following  files: 

~ cpanel /hsphere /WEB- INF /web . xml 
~cpanel/apache/ etc/mod_j  k . conf 
~ cpanel/ j akarta/ con f / server . xml 
~ cpanel/ shiva/ shiva- templates/ index . html 

Original  configuration  files  are  backed  up: 

-'-cpanel/hsphere/WEB-INF/web  . xml . ORG 
~cpanel/apache/ etc/mod_j  k . conf . ORG 
cpanel/ j akarta/ conf/  server  . xml . ORG 
cpanel/ shiva/ shiva-templates/index  . html . ORG 

Important:  Don’t  forget  to  run  this  script  after  the  Parallels  H-Sphere  update  to 
apply  your  CP  URL  customization  in  the  new  version! 


4.  Restart  Parallels  H-Sphere  (on  page  41). 
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Setting  Multiple  Alternative  CP  URL’s 

> To  specify  several  alternative  CP  URL’s  for  main  Admin  CP: 

1.  Log  into  your  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Enter  the  hsphere  .properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 

3.  In  the  CPJHOST  field,  set  several  host  names  using  semicolon  as 
separator: 

CP_HOST=cp. testhost . com; cp. testhostl . com; 10.0.1.20 

4.  Restart  Parallels  H-Sphere  (on  page  41). 
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Migrating  Control  Panel  Server 

By  server  migration  we  mean  moving  applications  and  data  from  one  server  to  another 
while  keeping  old  IPs  for  the  new  server. 

Note:  We  highly  recommend  performing  the  CP  server  migration  only  if  you  have 
practical  experience  with  Unix-based  systems.  We  will  not  be  responsible  for  the 
results  of  migration. 

It  is  not  recommended  to  erase  data  on  the  old  server  in  case  you  forget  to  move 
something  or  if  you  need  any  data  from  the  old  server.  It  is  safer  to  shut  down  the  old 
server  after  you  check  the  functionality  upon  migration. 

> To  perform  Control  Panel  server  migration: 

1.  Install  Parallels  H-Sphere  Control  Panel  software  on  the  target  server 
(make  sure  to  use  the  same  Parallels  H-Sphere  version  that  is  running 
on  the  source  server). 

Note:  If  your  source  server  is  also  running  Site  Studio,  make  sure  to  install  Site 
Studio  on  the  target  server  as  well. 

2.  Stop  Control  Panel  (on  page  41)  and  SiteStudio  on  both  source  and 
target  servers. 

3.  Dump  Parallels  H-Sphere  and  Site  Studio  databases  on  the  source 
server  and  then  restore  them  on  the  target  server. 

4.  Move  the  following  directories  to  the  new  server: 


Directory 

Files 

/hsphere/ local /home/ cpa 
nel/shiva/psoft  config/ 

Parallels  H-Sphere  configuration  and 
properties  files 

/hsphere/ shared/ SiteStu 
dio/psoft  config/ 

Parallels  SiteStudio  configuration  and 
properties  files 

/hsphere /local /home/ cpa 
nel /apache/ etc/ 

Apache  configuration  and  properties 
files 

/hsphere /local /home/ cpa 
nel/ shiva/ shiva- 
t empl at es/ IMAGES 

Control  Panel  icons  and  images 

/hsphere /local /home/ cpa 
nel/ shiva/ custom 

Custom  Control  Panel  templates 

/hsphere/ shared/ SiteStu 
dio/var /websites 

Parallels  SiteStudio  user  data 

/hsphere /local /home/ cpa 
nel/ . kb/ 

Parallels  H-Sphere  knowledge  bases 

/hsphere /local /home/ cpa 
nel/ . attachments/ 

Trouble  Ticket  system  attachments 

/hsphere /local /home/ cpa 
nel/ shiva /packages 

Parallels  H-Sphere  Packages  (this 
directory  may  be  missing,  if  so  - don’t 
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move  it) 


Alternatively,  use  rsync  to  move  necessary  data  to  the  new  server: 

rsync  -arlpogvzt  -e  ssh  $login@$ip: $folder  $folder  if 

you  are  using  rsync  on  the  target  server 

rsync  -arlpogvzt  -e  ssh  $folder  $login@ $ip : $f older  if 

you  are  using  rsync  on  the  source  server 

Note:  Slogin  usually  is  root. 

1 . After  moving  the  directories  listed  above,  restore  the  correct  password  for  database 
access  from  Control  Panel. 

To  find  out,  what  password  is  set  currently,  on  Linux  run: 

grep  wwwuser  /var/lib/pgsql/data/global/pg_ps 

on  FreeBSD,  run: 

grep  wwwuser  /usr/local/pgsql/data/global/pg_ps 

Restore  the  password  by  editing 

/hsphere/ local /home/ cpanel/ shiva/ psof t conf ig/h sphere . propert 

ies  on  the  target  server,  changing  the  value  - to  the  currently  set  password  - in  the 
line  with  “db_password  =”  and  saving  this  file. 

2.  Switch  IPs  between  the  old  and  new  servers. 

To  find  main  server  IP  in  Linux,  go  to: 

/ etc/ sysconf ig/ network- scripts/ if cf g-ethO 
To  find  main  server  IP  in  FreeBSD,  go  to: 

/etc/rc.conf 

Also,  please  make  sure  that  main  server  IPs  are  excluded  from  the 
/hsphere /local /network/ IPs  file  (corresponding  IP  on  the  corresponding 
server). 

5.  Prevent  the  startup  of  Control  Panel  service  on  the  source  server  on 
reboot: 

For  Linux,  run: 

chkconf ig— level2345  httpdcp  off 
For  FreeBSD,  run: 

chmod  000  /usr/local/etc/rc . d/apachecp . sh 

6.  Reboot  both  servers  and  the  router.  Router  reboot  is  needed  to  clear 
ARP  cache.  You  can  also  do  it  using  other  methods. 

7.  Check  the  Control  Panel  functionality. 

If  you  want  to  perform  Server/IP  migration,  skip  steps  6-8  and  follow  the  instruction  on 
Changing  IPs  (on  page  39)  instead. 


Generating  SSH  Keys  for  Parallels  H- 
Sphere  Servers 
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Parallels  H-Sphere  Control  Panel  interacts  with  its  Unix-based  servers  via  SSH 
protocol.  For  user  to  have  permanent  access  to  Parallels  Pi-Sphere  remote  servers  and 
to  log  into  them  automatically  without  entering  password  each  time,  the  SSPI  public 
keys  for  the  cpanel  user  on  the  CP  box  should  be  copied  and  added  to  each  Unix  box 
in  Parallels  Pi-Sphere  cluster. 

Normally,  Parallels  Pi-Sphere  does  this  automatically  during  installation.  Plowever, 
sometimes  there  is  a need  to  regenerate  or  restore  SSPI  keys.  This  document  will 
guide  you  through  the  process  of  generating  SSPI  keys  on  the  CP  box  and  adding  them 
to  each  Parallels  Pi-Sphere  server. 

> To  generate  SSH  keys: 

1.  Enter  the  CP  box  as  the  cpanel  user  (on  page  53). 

2.  Check  if  you  have  SSPI  public  keys  generated  for  the  cpanel  user. 

RSA: 

$ cat  ~cpanel/ . ssh/identity .pub 
DSA: 

$ cat  ~cpanel/ . ssh/id_dsa .pub 

3.  If  any  of  these  files  does  not  exist,  generate  missing  SSPI  key  for  the 
cpanel  user  by  the  corresponding  command  (passphrases  must  be 
empty): 

RSA: 

$ ssh-keygen  -t  rsal 
DSA: 

$ ssh-keygen  -d 

4.  Place  the  public  SSPI  keys  of  the  CP  server’s  cpanel  user  into  the 
corresponding  files  in  the  /root/  . ssh  folder  on  each  Parallels  Pl- 
Sphere  box: 

1 . Log  into  an  Parallels  Pi-Sphere  box  as  root. 

2.  Create  the  authentication  key  files  for  root  if  they  don’t  exist: 

RSA: 

# touch  /root/ . ssh/authorized_keys 

DSA: 

# touch  /root/ . ssh/authorized_keys2 

3.  Insert  the  RSA  key  from  the  -cpanel/ . ssh/identity. pub  file  on  the  CP 
server  into  /root/ . ssh/authorized  keys  on  this  box, 

and  the  DSA  key  from  -cpanel/ . ssh/ id  dsa . pub  into 

/ root/  . ssh/authorized_keys2,  respectively. 
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Encrypting  Trouble  Tickets 

PGP  encryption  mechanism  is  implemented  in  Parallels  H-Sphere  trouble  ticket  system 
to  encode  and  decode  secure  parts  of  TT  messages. 

PGP  encryption  is  implemented  on  the  basis  of  the  Cryptix  package 
(http://www.crvptix.org/products/openpqp/index.html).  Cryptix  is  a Java  implementation 
for  OpenPGP  (http://www.ietf.org/html.charters/openpqp-charter.html).  Cryptix  jar  files 
should  be  located  in  the  ~cpanei/java_rt  directory  and  their  names  should  be 
included  into  CLASSPATH: 

cryptix- j ce -provider . jar 
cryptix-message-api . j ar 
cryptix-openpgp -provider . jar 
cryptix-pki-api . j ar 
cryptix32 . j ar 


In  this  section: 


Generating  PGP  Public  Key  and  PGP  Private  Key 96 

Enabling  PGP  Encryption  In  Your  Support  Center 96 

Encrypting  Texts  With  PGP  Public  Key 97 

Using  Encrypted  Parts  in  Trouble  Tickets 98 


Generating  PGP  Public  Key  and  PGP  Private  Key 

To  generate  a pair  of  PGP  public  and  private  keys,  use  any  PGP  encryption  program. 

Or,  you  may  use  the  KeyPairGenerator  Java  tool  integrated  into  Parallels  H- 

Sphere: 

j ava  psof t . hsphere .tools . KeyPairGenerator 
-i  "This  is  a main  identification  string" 

-s  "identification  string  for  subkey" 

-e  "PGP  Code  Phrase" 

-prf  "/path/PGP  Private  Key/file" 

-pcf  "/path/ to/PGP_Public_Key/ file" 


Enabling  PGP  Encryption  In  Your  Support  Center 

Set  PGP  Private  Key  and  PGP  Code  Phrase  in  the  Settings/Tech  Support  menu  in  the  admin 
panel  to  be  able  to  decode  encrypted  texts  directly  from  TT  Administration  Center. 
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Encrypting  Texts  With  PGP  Public  Key 

PGP  Public  Key  should  be  made  available  to  customers  to  encrypt  their  messages. 

Information  may  be  encrypted  by  means  of  the  PGPEncrypter  Java  tool  in  Parallels  hl- 
Sphere: 

j ava  psof t . hsphere .tools . PGPEncrypter 
-m  "This  is  a message  to  encrypt" 

-f  "This  is  a file  where  encrypted  phrase  will  be  saved" 

-k  "/path/to/PGP  Public  Key/file" 
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Using  Encrypted  Parts  in  Trouble  Tickets 

The  following  example  represents  the  completely  formed  message  with  encrypted 
information: 

information  is  beyond BEGIN  PGP  MESSAGE 

Version:  Cryptix  OpenPGP  0.20030205 

hQEOA/d04g5fFsnOEAP+LZ+xiV66LWcK/xoRd7aFvUiSnJOZD57hiuACvccPPc2A 

eOFELnqdnOcbabXbsG7W7YfYCYfGQzqesOeTfxoO/EXOtB9WGHZ45pZfBYRJC517 

F4Olfg0+KES5l1/oEaGgy77jzSPAYfsYDOYnrKW2f0ldlBAk37MnjY4Uk+09l6oD 

/3FJxlEF4p2G4IZ1tAFJAFIAdgN1TivZQ3cJ24fTd0sFzRbuo2GeirF7jC35RI7hN 

vDwCnqNWIPMpHrs4uAOOsvD/nKSDML+LIPCoK9YUr+NKj1  ECUyXIAzfNKOOo8nyN 

foNzqe3zfY0148yL0gYtDrKR8SPa+ILQv/30Ke7lr1YdpCo9H+U4dLUBNRLkNveK 

Ls9MyuleAd20M0Pllm0mxAMGEK2avjPlj0dU+PDi8= 

=fHh9 

— END  PGP  MESSAGE-—  the  invisible 

In  the  CP  trouble  ticket  center  this  message  will  be  displayed  as: 

information  is  beyond  - — BEGIN  PGP  MESSAGE— -secure  information- — END  PGP 
MESSAGE- — the  invisible. 

In  order  to  read  the  encrypted  information,  click  on  the  link  Click  here  to  access 
encrypted  information.  Decrypted  information  would  appear  in  a separate  window. 

The  ticket’s  encrypted  part  would  not  be  revealed  in  the  reply  message  received  by  the 
customer: 


========  CUT  HERE  ========= 

Your  support  request  was  answered: 

Created:  Feb  1 1 , 2004  3:27:45  PM 
Last  Mod:  Feb  1 1 , 2004  3:28:02  PM 

Assigned  To:  admin(Admin  Account"!) 


[Feb  11, 2004  3:28:46  PM] 
A:  Hello 


[Feb  11, 2004  3:27:45  PM] 

Q:  information  is  beyond  | secure  information  | the  invisible. 

To  learn  more  about  encrypted  messages  in  trouble  tickets,  please  refer  to  the 
Providing  Customer  Support  documentation  in  Parallels  H-Sphere  Service 
Administrator  Guide. 
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Customizing  Domain  Registration  Lookup 
Script 

Custom  domain  registration  lookup  script  is 

/hsphere/shared/scripts/custom  reg.  H-Sphere  uses  the  whois  command 
to  figure  out  whether  domain  is  already  registered  or  not.  Different  domain  registration 
servers  respond  in  different  way,  so  it  is  almost  impossible  to  keep  the  script  up-to-date 
to  properly  support  all  potential  TLD’s. 

In  H-Sphere  3.2  we  introduce  the  built-in  /hsphere/ shared/ scripts/ custom  reg 
with  a minimal  code.  Instead,  H-Sphere  system  administrator  will  be  able  to  create  and 
Customize  the  /hsphere/ shared/ scripts/pkg_scripts/ custom_reg  Script.  H- 
Sphere  will  check  if  the  latter  script  exists  and  thus  invoke  it. 

Here  is  an  example  of  the  script: 

#!/bin/sh 

free_domain_pattern=”No  match  for” 
if  [[$1  = *.be  ]];  then 

free  domain_pattern="Status : \s*FREE" 

fi 

if  [[  $1  = *.mobi  ]];  then 

free  domain  pattern="NOT  FOUND" 

fi 

if  [[$1  = *.nl  ]];  then 

free  domain  pattern="is  free" 

fi 

if  [[  $1  = *.it  ]];  then 

free  domain  pattern="Status : \s*AVAILABLE" 

fi 

if  [[  $1  = *.uk  ]];  then 

free  domain  pattern="This  domain  name  has  not  been 
registered. " 

fi 

if  [[  $1  = *.eu  ]];  then 

free  domain  pattern="Status : \s*FREE" 

fi 

if  [[  $1  = *.name  ]];  then 

free  domain  pattern="No  match." 

fi 

whois  $1  | grep  “$free_domain_pattern”  2>&1  >/dev/null;  echo  $? 
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Web  Server 

This  chapter  instructs  you  on  some  task  you  may  need  to  perform  on  Parallels  Id- 
Sphere  Unix  Web  server. 

In  this  chapter: 

Understanding  Web  Server  Configuration 101 

Preventing  Manipulation  with  Logs  Directory  Permissions 114 

Altering  Virtual  Host  Configuration 114 

Calculating  Web  T raffic 116 

Adding  Directories  for  User  Homes 120 

Installing  Ruby  on  Rails 120 

Installing  ChiliiSoft  ASP 121 

Installing  mod_perl 128 
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Understanding  Web  Server  Configuration 

The  following  software  is  installed  on  Parallels  H-Sphere  Unix  Web  boxes: 

Core  services: 

■ Apache  Web  Server:  support  of  Apache  1 .3.x  and  2.2.x.  PHP  comes  as  separate 
packages. 

■ ProFTPd  FTP  Server  (on  page  102) 

Additional  software: 

■ SSL  support:  OpenSSL  (on  page  106) 

■ PPIP  (on  page  281): 

■ PPIP  4 - all  supported  Parallels  Pi-Sphere  versions. 

■ PPIP  5 - Parallels  Fl-Sphere  2.5  and  later. 

■ PPIP  5.3  - Parallels  Pi-Sphere  3.6  and  later. 

■ PPIP  5.4  - Parallels  Pi-Sphere  3.6.2  and  later. 

■ PPIP  5.5  - Parallels  Pi-Sphere  3.6.3  and  later. 

■ Perl  (on  page  268) 

■ Third-party  log  analyzers  (on  page  106)  (Web  statistics  calculators): 

■ Webalizer,  ModLogAn,  AWStats  - included  into  Parallels  Pi-Sphere  default 
installation. 

■ Urchin  v.3.xx,  4.xx,  5.xx  - supported  but  not  included  into  the  installation. 

■ Webshell  (on  page  109)  - Parallels  Pi-Sphere  integrated  Web  directory  file 
manager. 

■ MnoGoSearch  (on  page  1 10)  - search  engine  that  indexes  websites  by  keywords. 

■ Jail  (on  page  1 1 2)  - chrooted  shell  environment  with  a set  of  widely  used  utilities 
and  file  managers. 

Security  schemes: 

■ Webbox  security  scheme  (on  page  1 14)  - preventing  manipulation  with  logs 
directory  permissions. 


In  this  section: 


FTP  Server 102 

SSL  Implementation  on  Unix  Web  Servers 106 

Third  Party  Log  Analyzers  Integrated  in  Parallels  H-Sphere 106 

WebShell 109 

MnoGoSearch 110 

Parallels  H-Sphere  Jail 112 
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FTP  Server 

Parallels  H-Sphere  FTP  is  based  on  ProFTPd  server  and  installed  on  Web  boxes  as 

hsphere-ftp-<vers/on>-<bu//d>  package,  where  <version>  is  ProFTPd  version,  and  <build> 

is  this  package’s  build  number. 

ProFTPd  binary  is  /hsphere/ shared/ sbin/proftpd. 

Please  refer  to  the  original  ProFTPd  site  for  Configuration  Directive  List, 
http://www.proftpd.org/docs/directives/linked/confiquration.html. 

There  are  two  kinds  of  FTP: 

■ User  FTP:  When  a new  user  account  is  created,  its  user  is  provided  with  the  FTP 
account  and  thus  may  download/upload  files  from/to  the  user’s  home  directory 
(/hsphere / local /home / <user_name>)  by  FTP  using  its  name  and  password. 

■ Virtual  (anonymous)  FTP:  a service  provided  only  for  dedicated  IP  accounts, 
enables  to  create  virtual  accounts  to  download/upload  files  from/to  virtual  account 
directories  that  are  located  within  the  account  home  directory,  and  provides 
anonymous  access  to  the  public  directory. 


In  this  section: 


User  FTP 103 

Virtual  FTP 104 

FTP  Over  SSL/TLS 105 
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User  FTP 

Log  File 

When  a user  uploads  or  downloads  data,  the  corresponding  record  is  made  in  the  log 
files: 

/hsphere/local/var/prof tpd/xf erlog - FTP  log 
/hsphere/local/var/ prof  tpd/ tls  . log  - TLS/SSL  log 

Configuration 

/hsphere/ shared/ conf  ig/ f tpd  - FTP  configuration  directory 

/hsphere/ shared/ config/ ftpd/proftpd.  conf  - FTP  configuration  file 

/hsphere/  shared/ con  fig/ ftpd/proftpd  .conf. shared  - FTP  subaccounts’ 
configuration  file 

/hsphere/local/ config/ f tpd/lservers/web  <Shared_IP>  . conf  - configuration 
files  of  logical  servers’  vitrual  hosts 

/hsphere/local/config/f  tpd/sites  ■ users’  vitrual 
hosts 

Read  how  to  make  changes  into  FTP  config  files  in  Appendix  C.  Customizing  Server 
Configuration  Files  of  Parallels  H-Sphere  Installation  Guide. 

Download/Upload  Permissions 

Users  can  download  and  upload  files  from  his  document  root  directory 
(/hsphere /local /home / <user_name> / <domain_name>)  after  they  log  in  by  FTP 
entering  their  login  name  ( <user_name> ) and  password: 

ftp  user_name@domain_name 


User  FTP  Traffic  Calculation 

Cron  (on  page  33)  runs  the 

/hsphere/ shared/ scripts/ cron/ f tp_anlz_user . pi  script  on  everyday  basis 
for  collecting  user  FTP  traffic. 

ftp  anlz  user . pi  parses  the /hsphere/local/var/prof tpd/xf erlog  FTP 

log  file  and  writes  FTP  traffic  statistics  into  the 

/hsphere/local/var/ statistic/ dd .mm.  YYYY  . gst . txt  Statistics  files. 

The  TrafficLoader  (on  page  36)  Java  class  utility  is  launched  by  cron  to  process  FTP 
traffic  statistics  and  load  it  to  the  system  database.  TrafficLoader  also  calls  the 

/hsphere/ shared/ scripts/xf  er_cat . pi  to  gzip  outdated  Statistics  files  and 
move  them  into  the  loaded  directory  where  they  are  stored  as 

dd. mm . YYYY . gst . txt . gz  archives. 
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Virtual  FTP 

Log  File 

For  each  virtual  account,  its  own  configuration  file  is  located  in  the 

/hsphere/local/var/  prof  tpd/ logs  / directory.  File  format:  <vhost_id> . ftp . log. 

For  example,  wwwuser  has  virtual  FTP  enabled  for  the  test  .psoft  virtual  host,  and 
vhost_id=i2 08  is  the  virtual  host  identifier.  When  the  virtual  FTP  user  test3  connects 
by  FTP  to  the  virtual  host  (ftp  test3@test . psoft),  he  would  be  allowed  to 
download  and  upload  (if  permissions  to  write  are  set  to  that  virtual  host)  from 

/hsphere/iocai/home/wwwuser/1208  directory  for  downloads  and 
/hsphere/local/home/wwwuser/1208/ incoming  directory  for  uploaded  files. 

The  log  records  would  be  added  to 

/hsphere/local/var/proftpd/logs/1208 . ftp. log 

The  same  is  true  for  anonymous  FTP  account.  If  this  option  is  enabled  for  the  test. psoft 
virtual  host,  any  user  may  connect  by  FTP  using  anonymous  login  and  any  email  as  a 
password,  and  all  his  downloads  would  go  to 

/hsphere/local/home/wwwuser/1208  directory,  uploads  to  the 
/hsphere/local/home/wwwuser/12  08/ incoming  subdirectory. 

Configuration 

Configuration  directory  is  /hsphere/iocai/config/ftpd. 

The  sites  subdirectory  contains  configuration  files  <vhost_id> . conf.  These  files  are 
generat  ed  by  Parallels  Pi-Sphere  when  the  new  virtual  FTP  server  is  created,  by 
parsing  the  /hsphere/local/home/cpanel/shiva/shiva- 
tempiates/ common/ ftp/ ftp . conf  ig  template  where  the  structure  of  virtual  host 
configuration  is  set. 

The  sites/ index . conf  file  contains  the  inclusions  of  the  <vhost_id> . conf  files. 

The  sites/<v/josf_/cf>.passwd  files  contain  information  on  the  following  accounts: 

- <web_user_name>  - name  of  the  web  user  under  which  account  this  virtual  host  is 
enabled.  Thus,  user  may  log  on  by  his  name  and  password  to  connect  by  FTP  to  the 
virtual  host  FTP  directory. 

- <anonymous>  - if  anonymous  FTP  is  switched  on,  anonymous  connection  may  be 
established  by  the  outsider. 

- the  list  of  virtual  FTP  users  with  their  base64-encoded  passwords. 

/hsphere/iocal/ config/ ftpd/proftpd.  conf  - configuration  file.  It  includes  the 
user  FTP  configuration  file  and  sites/index . conf  file. 

Virtual  FTP  Traffic  Calculation 


Cron  (on  page  33)  runs  the  /hsphere/ shared/ scripts/ cron/ f tp_anlz  . pi 

script  daily  to  collect  virtual  FTP  traffic  statistics. 

The  script  parses  the  virtual  FTP  log  files  and  writes  traffic  statistics  into  the  timestamp- 
named  /hsphere/local/var/ statistic/ dd.mm.  YYYY  . ftp  . txt  Statistics  files. 
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The  TrafficLoader  (on  page  36)  Java  class  utility  is  launched  by  cron  to  process 
anonymous  FTP  traffic  statistics  and  load  it  to  the  system  database.  TrafficLoader  also 
calls  the  /hsphere/ shared/ scripts/xf er_cat . pi  to  gzip  outdated  statistics  files 
and  move  them  into  the  loaded  directory  where  they  are  stored  as 

dd . mm . YYYY . f tp . txt . gz  archives. 

FTP  Over  SSL/TLS 

Parallels  H-Sphere  3.1  implements  FTP  over  SSL/TLS  by  adding  mod_tls  module 
(http://www.castaqlia.orq/proftpd/doc/contrib/ProFTPD-mini-FIOWTO-TLS.html).  If 
client  software  supports  TLS,  encryption  is  used,  if  not  - FTP  client  operates  in  ordinary 
mode. 

FTP  over  SSL/TLS  works  with  shared  SSL  certificates  (on  page  106)  on  standard  FTP 
ports  (20/21). 

The  /hsphere /local/ config/f tpd/ script s/ftp-sharedssl.sh  script  which 
runs  after  installing  the  FTP  software  creates  virtual  configs  from  the 
/hsphere/iocal/ conf  ig/ f tpd/isrv . conf . tmpi  template  for  each  shared  IP  - 
/hsphere/local/ conf  ig/f  tpd/ lservers/web  <Shared_IP>  . conf  that  take 
prof  tpd  configuration  from  the  lservers  directory. 

f tp-sharedssi . sh  script  runs  also  after  each  restarting  of  the  FTP  server,  and  all 
virtual  hosts  are  regenerated  anew. 

Please  refer  to  FTP  client  software  which  support  FTP  over  SSL: 

■ http://www.ford-hutchinson.eom/~fh-1-pfh/ftps-ext.html#client 

■ http://hp.vector.co.ip/authors/VA027031/orenosv/ftps.html 

■ http://www.vicman.net/lib/ftps/client 
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SSL  Implementation  on  Unix  Web  Servers 

This  document  covers  SSL  implementation  on  Parallels  H-Sphere  Unix  Web  servers. 

SSL  is  implemented  by  the  mod_ssi  Apache  utility  and  uses  OpenSSL  package 
installed  on  the  box.  Parallels  H-Sphere  uses  native  OpenSSL  packages  installed  with 
operating  systems. 

There  are  two  SSL  modes:  dedicated  and  shared. 

Dedicated  SSL 

In  dedicated  SSL  mode,  a single  SSL  certificate  is  issued  for  a dedicated  IP. 

For  dedicated  IPs,  SSL  keys  are  located  in  the  user  home  directory: 

/hsphere/ local /home /<user_name>/ ssl . conf  / <domain_name> / 

If  SSL  is  enabled,  the  following  files  will  be  placed  to  this  directory: 

■ server,  crt  - SSL  certificate 

■ server . key  - SSL  private  key 


Shared  SSL 

In  shared  SSL  mode,  one  SSL  certificate  would  be  used  for  all  IPs  under  the  same 
domain  zone. 

Directories  with  SSL  certificates  and  keys  are  located  in  the  Apache  config  directory 

(/hsphere/ shared/ apache/ config/). 

/hsphere/ shared/ apache/ conf/  ssl . shared  - directory  for  shared  SSL 
certificates  and  keys. 

Shared  SSL  directory  structure: 

■ ss\.shared/<domain_name>  - directory  with  SSL  certificate  and  private  key  for  a 
domain 

With  SSL  enabled,  the  following  files  are  placed  into  this  directory: 

■ server . crt - SSL  Certificate 

■ server . key  - SSL  Private  Key 

■ server . csr  - SSL  signing  request  (if  certificate  has  been  generated  by  Parallels 
Pi-Sphere  SSL  generator  tool) 

When  the  user  turns  SSL  off,  the  files  remain  on  the  server.  When  the  user  turns  SSL 
back  on,  they  are  overwritten  with  the  new  files. 

Third  Party  Log  Analyzers  Integrated  in  Parallels  H- 
Sphere 

Parallels  Pi-Sphere  integrates  the  following  third-party  log  analyzers  (traffic  calculators): 
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■ Webalizer 

■ ModLogAn 

■ AWStats 

■ Urchin 

Please  also  refer  to  Web  T raffic  Calculation  in  Parallels  H-Sphere  (on  page  116). 


In  this  section: 
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Webalizer 

Webalizer  (http://www.webalizer.com/)  is  one  of  the  most  popular  traffic  log  analyzers. 

It  is  included  to  default  Parallels  H-Sphere  installation  and  available  for  Linux-hosted 
accounts.  Webalizer  analyzes  transfer  log  and  generates  readable  HTTP  transfer 
reports  for  a domain. 

To  activate  the  Webalizer  resource,  the  Transfer  Log  resource  must  be  enabled. 

Webalizer  is  installed  as  the  hsphere-webaiizer-<vers/'on>-<fau/7cf>  package,  where 
<version>  is  Webalizer  version,  and  <build>  is  this  package’s  build  number. 

/hsphere/ shared/bin/webalizer  - Webalizer  installation  directory. 

/hsphere/ shared/ apache/ conf /webalizer  user.cfg  - Webalizer  COnfig  file. 

In  Parallels  H-Sphere  scripts  directory,  the  following  scripts  are  used  for  Webalizer 
activation  and  update: 

■ /hsphere/ shared/ scripts/webalizer-init  - script  for  Starting  Webalizer 

■ /hsphere/ shared/ scripts/webalizer-stop  - Stop  Webalizer 

■ /hsphere/ shared/ scripts/webalizer-update  .pi  - Perl  script  for 
Webalizer  update 

Webalizer  directory  for  a domain: 

/hsphere/local/home/<use/>/<do/77a/rj.rja/77e>/webaiizer/. 

Webalizer  statistics  for  a domain  can  be  viewed  at 

http:  //<domain.name>/webalizer/ 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
116). 
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ModLogAn 

ModLogAn,  http://www.modloqan.org/,  is  a third-party  traffic  calculation  utility,  similar  to 
Webalizer. 

To  activate  the  ModLogAn  resource,  Transfer  Log  must  be  enabled. 

ModLogAn  is  installed  as  the  hsphere-modiogan-<vers/on>-<bu//d>  package,  where 
<version>  is  ModLogAn  version,  and  <build>  is  this  package’s  build  number. 

/hsphere/shared/bin/modlogan  - ModLogAn  installation  directory. 

/hsphere/shared/ apache/ conf /modlogan  user  . cfg  - ModLogAn  COnfig  file. 

In  the  Parallels  H-Sphere  scripts  directory,  the  following  scripts  are  used  for  ModLogAn 
activation  and  update: 

■ /hsphere/ shared/ scripts/modlogan-init  - script  for  ModLogAn 
initialization. 

■ /hsphere/ shared/ scripts/modlogan-stop - Stop  ModLogAn 

■ /hsphere/ shared/ scripts/modlogan-update  .pi  - Perl  script  for  ModLogAn 
update 

ModLogAn  directory  for  a domain: 

/hsphere  /local  /home / <user>/<domain.name> /modlogan  / . 

ModLogAn  statistics  for  a domain  can  be  viewed  at 

http:  //<domain.name>/modlogan/ 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
116). 

AWStats 

AWStats  is  a free  tool  that  generates  advanced  graphical  web  server  statistics  reports. 
AWStats  is  set  up  on  each  Unix/Linux  and  Windows  web  server  with  Parallels  H- 
Sphere  installation  or  upgrade.  Statistics  is  calculated  for  each  domain  separately. 

AWStats  is  installed  as  the  hsphere-awstats-<version>-<build>  package,  where 
<version>  is  AWStats  version,  and  <build>  is  this  package’s  build  number. 

AWStats  installation  directory:  /hsphere/shared/awstats. 

Each  domain  has  its  own  AWStats  configuration  file: 

/hsphere/local/home  /<user>  / <domain.name>  / cgi- 
bin/awstats  . <domain.name> . conf 

AWStats  log  directory  for  a domain: 

/hsphere/ local /home /<user>/<domain.name>/ awstats/ data/ 

AWStats  statistics  for  a domain  can  be  viewed  at  http : //<domain.name>/cgi- 

bin /awstats . pi 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
116). 
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Urchin 

Urchin  is  a third  party  Web  analytics  software  integrated  into  Parallels  H-Sphere. 

Urchin  is  installed  and  configured  separately  (on  page  354). 

Urchin  directory:  /hsphere/local/urchin. 

Urchin  collects  statistics  for  each  domain  into  the 

/hsphere/  local  /ur  chin  /var/  logs  /urchin-<domain_ict>  .log  files.  This 
statistics  is  transferred  to  the  Urchin  remote  server  via  HTTP  by  means  of  the  print- 
log,  pi  script  located  in  cgi-bin  directory  of  each  domain  directory. 

Log  file  with  Urchin  history:  /hsphere/local/urchin/data/history. 

WebShell 

WebShell  is  the  Parallels  H-Sphere  web-based  file  manager  that  enables  to  browse, 
access,  and  protect  remote  directories  without  knowing  the  Unix  file  structure.  It  allows 
to  copy,  move,  delete,  and  rename  files  and  directories  in  the  home  directory  on  the 
server.  Also,  it  can  be  used  to  upload,  download,  compress  and  decompress  files  as 
well  as  preview  them  in  the  browser. 

WebShell  is  installed  with  Web  server  by  means  of  hsphere-websheii  package, 
/hsphere/ shared/ apache/htdocs/webshell4  - WebShell  4 installation  directory. 


In  this  section: 


WebShell  CGI  Mode 
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WebShell  CGI  Mode 

Regular  WebShell  (SO  mode)  requires  that  certain  modules  (exec,  proc_open,  and 
some  others)  are  enabled  in  php.ini.  However,  more  restricted  security  schemes  have 
these  modules  disabled.  In  this  case,  WebShell  CGI  mode  is  developed  to  work  in 
standalone  PHP  environment. 

WebShell  CGI  mode  package  is  hsphere-websheii-cgi. 

/hsphere/ shared/ apache/htdocs/webshell5  - WebShell  CGI  directory. 

> To  switch  to  WebShell  CGI  mode: 

1.  Go  to  admin  CP,  E. Manager ->  Servers  ->  L.Servers  menu. 

2.  Choose  WebShell5  (CGI  Mode)  option  in  Additional  Options. 

After  that,  WebShell  in  CGI  mode  will  be  available  for  a virtual  host  at: 

http:  / /<VirtualHost>/webshell5/index2  . wsh 

Specific  WebShell  CGI  Mode  features: 

■ User  authentication  procedure  uses  unixserver  daemon  (based  on  daemontools) 
with  pwgetquota  utility 

■ pwgetquota  utility:  returns  user  quota  limits  and  login  status 

■ standalone  PHP  instructions  are  added  to  the  .htaccess  file  in  the  websheii5 
directory  and  to  Apache’s  httpd.conf 


MnoGoSearch 

MnoGoSearch,  http://www.mnoqosearch.org/,  is  a web  search  engine  that  searches 
your  site  by  keywords.  It  can  run  on  both  intranet  and  Internet  pages.  MnoGoSearch  is 
installed  into  Parallels  H-Sphere  from  a single  package  hsphere-mnogosearch- 
<version>-<build> , where  <version>  is  MnoGoSearch  version,  and  <build>  is  this 
package’s  build  number. 

All  MnoGoSearch  files  are  installed  in  /hsphere/shared/mnogosearch,  except  for 

mnogosearch-init  and  mnogosearch-set  scripts,  that  are  placed  to 
/hsphere/ shared/ scripts. 

For  the  proper  work  of  MnoGoSearch,  you  will  also  need  the  file 
~ ht  tpd/ con  f/mno  go  search . conf  that  assigns  domains  but  is  not  included  in  the 
package  hsphere-mnogosearch-x . x . x. 


In  this  section: 
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MnoGoSearch  Configuration  Scripts 

mnogosearch-init 

mnogosearch-init  script  is  used  to  enable/disable  MnoGoSearch. 

Usage: 

mnogosearch-init  [ -f  homedir  ] [ -u  login  ] [ -g  group  ] [ -d  domain 
] [ -1  dblogin  ] [ -p  dbpasswd  ] [ -t  dbhost  ] [ -n  dbname  ] [ -a 
user_action  ] 

Where: 

■ homedir  - user  home  directory 

■ login  - user  name 

■ group  - the  group  to  which  the  user  belongs 

■ domain  - domain  name 

■ dblogin  - MnoGoSearch  database  login 

■ dbpasswd  - MnoGoSearch  database  password 

■ dbhost  - MnoGoSearch  database  host 

■ dbname  - MnoGoSearch  database  name 

user_action  - ‘set’  parameter  adds  MnoGoSearch,  ‘drop’  removes  When 
MnoGoSearch  is  being  enabled,  this  script: 

■ creates  for  the  domain  folder /user  homedir/mnogosearch/domain  name 

where  it  places  the  files  indexer . conf  and  search . htm.  A user  can  configure 
these  files  to  customize  indexer  and  frontend. 

■ in  the  folder /user  homedir/domain  name,  creates  the  folder 

f e_mnogosearch  where  it  places  PHP-frontend.  Now,  the  MnoGoSearch  can  be 
found  at  http : / /<domain_name>/ f e mnogosearch/ search . php 

■ creates  the  table  structures  by  running: 

/hsphere/ shared/mnogosearch/ sbin/ indexer  -Ecreate 
user  homedir/mnogosearch/domain  name/indexer . conf 

■ performs  indexing. 

When  MnoGoSearch  is  being  disabled,  the  mnogosearch-init  script  removes  all  the 
custom  settings. 

mnogosearch-set 

mnogosearch-set  script  is  used  to  add/remove  startup  links  from  the  server. 

Usage: 

mnogosearch-set  [ -a  | -r  ] [ -d  domain  ] [ -u  URL  ] 

Where: 

■ -a  - adds  startup  URL 

■ -r  - removes  existing  entering  URL 

■ domain  - domain  for  which  these  changes  are  done 
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■ URL  - URL  which  is  to  be  added  or  removed  This  script  is  executed  when  the 
startup  link  in  the  field  “Add  new  MnoGoSearch  URL”  is  submitted.  It  adds/removes 
the  startup  URLs  into/from  the  file 

user  homedir/mnogosearch/domain  name/indexer . conf 


MnoGoSearch  frontend 

MnoGoSearch  frontend  written  in  Perl  is  replaced  with  PHP-based  frontend. 

To  use  MnoGoSearch  with  PHP  frontend,  PHP  must  include  mnogosearch-php- 
extension.  See  Parallels  H-Sphere  PHP  (on  page  281)  documentation. 

Parallels  H-Sphere  Jail 

Parallels  H-Sphere  jail  shell  provides  chrooted  shell  environment  with  a set  of  widely 
used  utilities  and  file  managers.  It  is  implemented  via  hsphere-jaii -<version> 
package. 

If  the  corresponding  resource  is  enabled  for  the  account,  user’s  SSH  access  is  realised 
in  the  chrooted  enviroment  limited  by  the  user  home  directory. 

During  jail  execution  by  the  SSHD  daemon  the  formed  jail  skeletons  are  bound  to  the 
corresponding  mount  points  in  the  user’s  home.  For  this  purpose  jaild  daemon  is 
used,  which  communicates  with  jail  client  via  a UNIX  socket.  If  none  ssh  connections 
are  established  by  unix  user,  the  mount  points  become  unmounted  by  the  related  cron 
task  during  next  2 minutes. 

In  this  section: 
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Utilities 

hsphere- j ail  package  includes  a set  of  the  following  widely  used  utilities:  cat,  echo, 
In,  mkdir,  ps,  rm,  sh,  cp,  date,  kill,  Is,  mv,  pwd,  rmdir,  sleep,  md5/md5sum,  ping,  awk, 
diff,  find,  id,  sed,  tar,  whereis,  basename,  dirname,  grep,  Idd,  sort,  touch,  which,  cut, 
du,  head,  more,  tail,  vi,  whoami,  clear. 

These  utilities  with  the  corresponding  list  of  required  libraries  and  share  configuration 
directories/dbs  are  formed  in  the  predefined  location  during  package  install  and  may  be 
recreated  in  the  case  of  system  update  via  native  package  managers. 
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File  Managers 

The  following  widely  used  file  managers  are  available: 

■ me  (http://www.ibiblio.org/mc)  - GNU  Midnight  Commander 

■ ytree  (http://www.han.de/~werner/vtree.html)  - Ytree  a UNIX  Filemanager 

■ vifm  (http://vifm.sourceforge.net/)  - ViFM  a UNIX  Filemanager 


Scripts 

List  of  the  included  scripts  follows: 

■ /hsphere/local/conf ig/ j ail/scripts/check  j ail  Checks  whether 
utilities  and  their  libraries,  which  are  included  in  the  jail  environment,  were  changed 
(for  example  after  system  update).  If  so,  the 

/hsphere/ local/ conf ig/ jail/ scripts/ conf ig_j ail  is  executed. 

■ /hsphere/local/conf  ig/ j ail/scripts/config  jail  is  used  for  forming 
jail  environment  and  executed  in  the  post-install  package  section  or  via  the 
/hsphere /local/  conf  ig/ jail/  scripts/  check_j  ail  script. 

■ /hsphere /local/  conf  ig/ jail/  scripts/  j ailmount  is  a realization  of  jaild 
daemon  which  accepts  connection  from  the  jail  client  when  establishing  ssh 
connection.  It  requires  daemon  tools  and  unixserver  installed  on  the  boxes. 

■ /hsphere/local/conf  ig/ j ail/scripts/ j ailumount  is  a cron  task 
responsible  for  unmounting  unused  mountpoints  initiated  during  previous  SSFI 
connections  by  users  with  valid  jail  shell. 
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Preventing  Manipulation  with  Logs 
Directory  Permissions 

The  security  scheme  prevents  untrusted  users  from  manipulating  logs  directory  and 
prohibits  users  other  than  httpd  from  entering  user  directory.  The  example  of  the 
permissions  and  groups  associated  with  the  directories  in  the  security  scheme  is  as 
follows: 

d— rwx — t 3 root  january  4096  Dec  8 20:32  january 
where: 

■ d rwx— t - permissions  with  a sticky  bit  that  prevents  users  from  making  any 

changes  to  logs  directory 

■ root  - owner  of  the  directory  (should  not  coincide  with  the  user  name) 

■ january  - directory  name 

■ 4 096  - size  in  bytes 

■ Dec  8 20 : 32  - date  of  last  modification 

j anuary  - user  home  directory  name  Use  logslock  utility  to  put/remove  immutable 
flag  from  the  -userhome/iogs  directory: 

logslock  -h 

Usage: 

/hsphere/shared/bin/logslock  [ -p  directory  ] [ -u  directory  ] [-s]  [- 

a] 

p : set  sticky  bit  on  home  directory 
u : unset  sticky  bit  from  home  directory 

a : unset  sticky  bit  from  home  directories  of  Parallels  H-Sphere  users 
s : set  sticky  bit  on  home  directories  of  Parallels  H-Sphere  users 

Note:  The  above  mentioned  permission  settings  for  user  home  directory  may  cause 
user  access  denial  via  ssh  if  public  key  authentication  is  used.  To  avoid  the  problem, 
you  can  disable  strict  sshd  mode  by  editing  sshd_config  file  and  restarting  sshd 
daemon  (/ etc/ ssh/ sshd  conf  ig  file  on  Linux). 


Altering  Virtual  Host  Configuration 

Sometimes  you  might  want  to  alter  Parallels  H-Sphere  so  it  creates  some  additional 
entries  in  Virtual  Host  config  files  for  a particular  plan.  You  might  need  it  to  integrate 
java  hosting,  or  some  3rd  party  CGI.  For  this,  you  would  have  to  edit  the  file 

common/domain/vhost . config 

vhost . config  is  the  file  for  virtual  host  configuration.  It  has  a form  of  a template,  like 
any  other  template  used  in  Parallels  H-Sphere.  You  should  read  the  guide  on  template 
customization  in  Parallels  H-Sphere  Customization  Guide  and  create  custom  templates 
directory  as  well  as  make  a copy  of  the  file  before  you  start  modifing  the  file. 
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First  of  all,  choose  a paramter  to  separate  one  plan  from  another.  To  do  that,  go  to 
Plans->Manage,  and  click  settings  next  to  the  plan.  Set  variable,  like  tomcat_support 
l.  After  that,  open  the  vhost.  config  template,  and  add: 

<if  account. plan. values. TOMCAT_SUPPORT  ==  “1”> 

</if> 

Within  this  IF  clause,  do  whatever  you  got  to  do  for  that  virtual  host  config.  This  way, 
only  plans  with  that  setting  would  have  this  entry. 

There  are  3 scripts  that  are  used  for  domain,  on  domain  creation,  deletion,  and  when 
some  alteration  to  the  config  is  done.  This  is  how  they  are  called: 

■ On  domain  creation: 

apache-vhost 
apache- save conf 

■ On  domain  removal: 

apache -del conf 

■ On  update: 


apache- save conf 


Script 

Description 

Parameters 

/hsphere/ shared/ scr 

ipts/apache- 

saveconf 

creates  a site 
configuration  file 

$1  - id  of  the  site 

/hsphere/ shared/ scr 
ipts/ apache-delconf 

deleting  vhost  file 

$1  - id  of  site  configuration 
removed  (we  don’t  remove  files) 

/hsphere/ shared/ scr 
ipts /apache -vhost 

creating  vhost 
directory 

$l  - directory  inside  user 

directory 

$2  - username 

$3  - group  name 

$4  - permission  to  the  directory 

$5  - domain 

$6  - instant  alias 

$7  - cpanel  login 

$8  - control  panel  url 

$9  - Parallels  SiteStudio  url 

$10  - Parallels  SiteStudio  class 

name  (you  should  not  care  about 

those,  it  is  done  for  the  first  page 

the  user  will  see) 
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Calculating  Web  Traffic 


Important:  Parallels  H-Sphere  2.5  Beta  1 and  up  introduces  a completely  different 
approach  for  traffic  calculation  and  log  rotation.  Now  it  takes  into  account  both 
incoming  and  outgoing  traffic.  Therefore,  after  you  upgrade  from  Parallels  H-Sphere 
version  earlier  than  2.5,  your  clients  may  find  their  traffic  relatively  increased. 

There  are  two  types  of  traffic  calculation  in  Parallels  H-Sphere: 

■ Traffic  calculation  by  third-party  log  analyzers  - Parallels  H-Sphere  writes  log  files 
for  each  customer’s  domain  into  respective  directories  to  make  them  available  for 
third-party  log  analyzers  included  into  default  installation:  Webalizer,  Modlogan,  and 
AWStats. 

■ Parallels  H-Sphere  built-in  traffic  calculation  - Parallels  H-Sphere  provides  its  own 
mechanism  of  traffic  calculation  used  in  billing.  Parallels  H-Sphere  traffic  reports  are 
available  in  admin  CP  as  Transfer  Traffic  Report  in  the  Reports  menu. 


In  this  section: 
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Using  Third-Party  Log  Analyzers  for  Traffic  Calculation 

HTTP  Logs  for  each  domain  are  located  in  the 

/hsphere/local/home/{user}/logs/<doma/n.name>/  directory,  in  the  following 
files,  provided  respective  resources  are  enabled: 

■ Transfer  log:  the  <domain.name>  file; 

■ Agent  log:  agent_log 

■ Referrer  log:  referrer  log 

■ Error  log:  error  log 

Here,  <user>  is  account  name,  and  <domain.name>  is  user  domain  name. 

Log  Rotation 

Parallels  H-Sphere  runs  daily  cron  script 

/hsphere/ shared/ scripts/ cron/ cron  rotate.pl: 

0 2 * * * nice  -15  /hsphere/shared/scripts/cron/cron_rotate . pi 

Log  rotation  data  is  taken  from  the 

/hsphere/local/ conf  ig/httpd/logrotate_conf  s/  directory.  The  files  there 
look  like: 

■ Transfer  log:  <domain.name> . transferiog.  conf 

■ Agent  log:  <domain.name> . agentlog . conf 

■ Referrer  log:  <domain.name> . ref  erreriog . conf 

Error  log:  <domain.name> . erroriog . conf  The  cron  rotate . pi  script: 

1 . Rotates  current  log  files  in  the  /hsphere/local/home/{user}/logs/{domain.name}/ 
directory  into  the  {domain. name}. 1 , {domain. name}. 2. gz,  {domain. name}. 3.gz  etc. 
files  (the  first  one  NOT  being  gziped).  For  example: 


• rw 1 user29  user29  0 Jan  9 20:24  domain2 9 . test 

-rw 1 user29  user29  392000  Jan  9 20:24  domain2 9 . test . 1 

-rw 1 user29  user29  1495  Jan  9 20:24 

domain2  9 . test . 2 . gz 

-rw 1 user29  user29  1496  Jan  9 20:11 

domain2  9 . test . 3 . gz 


1.  Runs  Webalizer’s,  Modlogan’s  and  AWStat’s  command-line  utilities  that 
parse  current  logs  and  store  them  into  respective  directories  for  each 
domain  in  format  readable  for  these  analyzers. 

2.  Webalizer,  ModLogAn  and  AWStats  take  statistics  from  the  access  log 
files  already  rotated.  Currently  used  access  log  files  for 
Webalizer/Modlogan/AWStats  are  specified  in  the  respective 

<LOG>. domain. name>Axt  files: 

■ Webalizer:  webalizer  .<domain.name> .txt 

■ Modlogan:  modlogan . <domain.name> . txt 

■ AWStats:  awstats  . <domain.name> . txt 
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cron_rotate  . pi  uses  the  /hsphere/ shared/ scripts /get logs  . pi  script  to 
update  the  latest  log  file  name  specified  in  these  files.  Also,  it  calls  Webalizer’s, 
Modlogan’s  and  AWStat’s  command-line  utilities  that  parse  current  logs  and  store 
them  into  respective  directories  for  each  domain  in  format  readable  for  these 
analyzers: 

■ Webalizer:  /hsphere /local /home /<user>/ <domain.name>/ webalizer/ 

■ Modlogan:  /hsphere /local /home /<user>/<domain.name>/rnodloqan/ 

■ AWStats:  /hsphere/local/home/<user>/ <domain.name> / awstats/ data/ 
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Calculating  Parallels  H-Sphere  Built-In  Traffic 

Traffic  Log 

Parallels  H-Sphere  uses  the  mod_psoft_traf  fic  module  to  write  a more  informative 
and  convenient  traffic  log  into  the 

/hsphere/local/var/httpd/logs/traffic_log  file.  Traffic  log  has  the 

following  format: 

<unix_timestamp>  <domain_name>  <incomingJraffic>  <outgoing_traffic> 

For  example: 

1 1 02091 887  domain.com  623  623 
1 1 02091 888  domain.com  65  1 32 

Analyzing  Logs 

Parallels  H-Sphere  runs  daily  the  /hsphere/ shared/ scripts/ cron/ analyze  . pi 

cron  (on  page  33)  script: 

0 0 * * * nice  -15  /hsphere/shared/scripts/cron/analyze . pi 
/hsphere/ local /var/httpd/ logs /traf f ic_log 

The  script  parses  traffic_iog  and  writes  specially  formatted  dd.mm.YYYY.txt  http 
log  files  in  the  /hsphere/iocai/var/ statistic  directory  (dd.mm.  yyyy  is  date 
timestamp). 

Log  format: 

|<doma/rj.na/77e>|incoming_traffic|outgoing_traffic| 

TrafficLoader 

TrafficLoader  Parallels  H-Sphere  Java  class  is  in  charge  of  parsing  server  traffic.  It  is 
launched  daily  by  cron  (on  page  33): 

30  5 * * * su  -1  cpanel  -c  'java  psoft . hsphere . Traf ficLoader' 

TrafficLoader  processes  Web,  mail,  FTP  and  virtual  FTP  traffic  in  the  formatted 
statistics  files  located  in  the  /hsphere/iocai/var/statistic  directory  and  inserts 
these  lines  into  the  translog  table  of  the  Parallels  H-Sphere  system  database. 

T rafficLoader  also  calls  the  /hsphere/ shared/ scripts/xf  er_cat . pi  script  to 
rotate  the  already  loaded  statistics  files  to  the 

/hsphere/local/var/ statistic/ loaded  directory  as  dd.mm.  YYYY . txt . gz 

archives. 
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Adding  Directories  for  User  Homes 

In  the  default  Parallels  H-Sphere  configuration,  user  homes  are  located  in 
/hsphere/local/home.  In  some  situations,  you  may  want  to  add  more  directories  for  user 
homes,  for  instance: 

■ You  need  to  add  a new  hard  drive.  In  this  case  you  must  mount  the  new  HDD 
partition  next  to  the  existing  home  directory: 

/hsphere/ local /home 2/ 

■ You  have  web  and  Unix  RealServer  running  on  the  same  box,  but  would  like  to 
keep  their  user  homes  in  different  directories.  In  this  case  you  must  create  a 
directory  for  RealServer  user  homes: 

/hsphere /lo cal /realhome/ 


You  can’t  add  directories  for  user  homes  outside  /hsphere/iocal/  subtree, 
because  this  is  where  apache  suexec  is  configured  to  run  users’  cgi  scripts. 


> To  add  a directory  for  user  homes: 

1.  In  your  admin  cp,  select  L.Servers  in  the  E.MANAGER  ->  Servers  menu. 

2.  Select  the  server  you’ve  added  the  directory  for,  and  at  the  bottom  of 
the  page  that  appears  enter  the  name  of  the  new  directory. 

As  a result  of  this  procedure,  old  user  homes  will  remain  functional  in  their  old  location, 
and  new  user  homes  will  be  created  in  the  new  directory  regardless  of  the  plan. 


Installing  Ruby  on  Rails 

Parallels  H-Sphere  includes  support  for  Ruby  on  Rails 

(http://www.rubvonrails.org/down)  via  FastCGI.  However,  before  enabling  it  in  hosting 
plans,  administrators  need  to  manually  install  Ruby  on  Rails  on  their  Unix  Web  servers. 

> To  install  Ruby  on  Rails: 

1.  Log  into  CP  server  as  cpanel . 

2.  ssh  to  a Web  server  where  you  will  install  Ruby  on  Rails. 

3.  Install  the  Ruby  package  from  its  home  page: 

1 . Download  the  latest  ruby  package  with  wget  for  Linux  or  fetch  for  FreeBSD  (in 
this  document  we  use  version  1 ,8-5p2  as  an  example,  but  the  version  could  be 
updated): 

wget  http : / /ftp . ruby-lang . org/pub/ruby/1 . 8/ ruby-1 .8.5- 

p2 . tar . gz 

2.  Untar  the  package: 

tar  zxvf  ruby-1 . 8 . 5-p2 . tar . gz 
cd  ruby-1 . 8 . 5-p2 

3.  Compile  and  install  the  package: 
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. /configure 
make 

make  install 

4.  Install  Ruby  Gems: 

1 . Download  the  latest  Ruby  Gems  version  with  wget  for  Linux  or  fetch  for 
FreeBSD  (in  this  document  we  use  version  0.9.4  as  an  example,  but  this  version 
could  be  updated): 

wget  http : //rubyforge . org/ frs /download .php/ 17 190/ rubygems- 

0.9.4. tgz 

2.  Untar  the  package: 

tar  xzvf  rubygems-0 . 9 . 4 . tgz 
cd  rubygems -0.9.4 
ruby  setup. rb 

5.  Complete  Ruby  on  Rails  installation: 

gem  install  rails— include-dependencies 

gem  install  -y  fcgi  --  — build-flags— with-fcgi- 

dir=/hsphere/ shared/ 

After  that,  switch  the  Ruby  on  Rails  resource  on  under  Web  Services  in  a Unix  hosting 
plan  to  enable  RoR  for  users. 


Installing  ChililSoft  ASP 

This  guide  describes  the  installation  of  ChililSoft  ASP  to  Parallels  H-Sphere  web  box. 

It  is  advisable  to  read  the  README  file  that  contains  Chili IASP  bundle  to  get  familiar 
with  ChililASP  general  issues  and  features. 

WORKFLOW 

1.  Download  ChililSoft  ASP  tarball. 

2.  Run  the  command 

# mkdir  casp 

3.  Run  the  command 

# tar  xf  chiliasp-3 . 6 . 2L . 1047a . tar  -C  casp 

4.  Run  the  command 

# cd  casp  &&  ./install 

5.  You  will  see  dialogue  windows  in  the  order  set  below.  We  shall  lead  you 
though  the  procedure  and  give  you  the  responces  required  for  the 
correct  Sun  ChililSoft  ASP  installation. 

On  each  step,  you  will  have  to  choose  one  of  the  options  suggested. 

The  default  choice  is  shown  in  square  brackets  e.g.  [1],  the  option  that 
you  need  to  choose  is  shown  in  bold  in  the  description  below  next  to  the 
default  one,  e.g.  [1]  2 - the  correct  choice  is  option  2. 
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Step  I. 


Sun  Chili !Soft  ASP  - Installation 


Setup  will  now  install  the  files  needed  to  run  and  configure  Sun  Chili ISoft  ASP  to  a 
directory  that  you  specify.  To  accept  the  default  (shown  in  brackets  below),  press 
Enter.  To  specify  a different  directory,  enter  the  pathname  and  then  press  Enter. 
Note:  Configuration  options  specific  to  this  installation  are  contained  in  the  directory 
that  you  specify.  Make  a note  of  this  location,  so  you  can  easily  find  Sun  Chili  ISoft 
ASP  files  at  a later  time. 


Enter  the  directory  in  which  to  install  Sun  Chili  ISoft  ASP  [/opt/casp] 

/hsphere/shared/casp 

Extracting  files  to  /hsphere/shared/casp  ... 

+ bean-classes  package  . done. 

+ bean-jre  package done. 

+ bean  package  . done. 

+ caspdoc  package done. 

+ caspsamp  package  ...  done. 

+ casp  package  . done. 

+ chilicom  package  ...  done. 

+ components  package  . done. 

+ installer  package  . done. 

+ license  package  . done. 

+ module  package  . done. 

+ odbc-direct-40  package done. 

+ odbc-opensource  package  . done. 

+ server  package  ..  done. 

+ sqlnk-4_51  package  . done. 

+ chili-tools-linux2  package  ..  done. 

+ supporting  binary  / library  packages  . done. 

Step  II. 


Sun  Chili  ISoft  ASP  - Product  Serial  Number 


Sun  Chili  ISoft  ASP  requires  a valid  serial  number  to  run.  If  you  downloaded  this 
product  from  the  Web,  you  should  have  received  an  e-mail  message  that  included 
your  serial  number.  If  you  are  installing  this  product  from  a CD-ROM,  the  serial 
number  is  printed  on  the  CD-ROM  case.  If  you  do  not  have  a serial  number,  enter 
‘n’  below  to  receive  a 30-day  trial  license. 

Note:  iPlanet  6.0  users  are  already  licensed  to  use  this  product  and  do  not  need  to 
enter  a serial  number.  If  you  are  using  iPlanet  6.0,  enter  ‘n’  below  to  receive  a full, 
unlimited  license. 


Do  you  have  a Sun  Chili  ISoft  ASP  Product  Serial  Number  (y/n)?  [y]  y 

Note:  If  you  wish  to  exit  out  of  the  license  key  installer,  type  none. 

Enter  your  Sun  Chili  ISoft  ASP  Product  Serial  Number 
[none]  Y_0_U_R_  S_E_R_I_A_L 


Step  III. 

Sun  Chili  ’Soft  ASP  - Bundled  Apache  1.3.19  Configuration 
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Sun  Chili !Soft  ASP  includes  a ready-to-run  Apache  1 .3.1 9 Web  server  that  is 
configured  with  Microsoft  ™ FrontPage  2002  Server 

Extensions  support  and  EAPI  (Extended  API).  If  you  have  not  yet  configured  a Web 
server,  you  now  have  the  option  to  install  this  preconfigured  Apache  Web  server. 

Note:  Sun  ChiliSoft  ASP  supports  but  does  not  install  FrontPage  2002  Server 
Extensions;  those  must  be  obtained  from  Microsoft.  For  more  information  about 
Sun  Chili ISoft  ASP  support  for  FrontPage  2002  Server  Extensions,  see  ‘Chapter  3’ 
in  our  production  documentation.  For  more  information  about  EAPI,  including  the 
mod_ssl  / OpenSSL  module,  visit  www.modssl.org 


Would  you  like  to  install  the  bundled  Apache  1 .3.19  Web  server  (y/n)?  [n]  n 

Step  IV. 


Sun  Chili  ISoft  ASP  - Language  Selection 


Sun  Chili  ISoft  ASP  supports  various  languages.  Select  the  language  you  want  to 
use  from  the  list  below. 

1 . English  - US 

2.  English  - British 

3.  Japanese  Shift-JIS 

4.  German 

5.  Dutch 

6.  Spanish 

7.  French 


Which  language  would  you  like  to  use?  [1]  1 

Step  V. 


Sun  Chili  ISoft  ASP  - Configuring  Java  Support 


The  Sun  Chili IBeans  component  allows  you  to  directly  access  Java  objects  and 
classes  from  inside  your  ASP  scripts.  For  this  functionality  to  be  provided,  a Java 
runtime  environment  (JRE)  must  be  installed.  Sun  Chili  ISoft  ASP  includes  JRE 
1 .3.1 . While  other  JREs  are  supported,  the  use  of  JRE  1 .3.1  is  strongly 
recommended.  Choose  option  1 to  use  the  bundled  JRE. 

1 . Use  the  bundled  JRE  1 .3.1 . 

2.  Specify  the  path  to  an  existing  JRE. 

3.  Disable  Java  support. 


Which  JRE  would  you  like  to  use?  [1]  3 

Are  you  sure  you  want  to  disable  Java  support  (y/n)?  [n]  y 
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Step  VI. 


Sun  Chili  ISoft  ASP  - Web  Server  Auto-Detection 


Setup  will  now  conduct  a search  of  your  system  to  generate  a list  of  installed  Web 
servers.  On  the  next  screen,  you  have  the  option  to  enable  ASP  support  for  one  of 
these  detected  Web  servers.  If  you  want  to  skip  this  step,  you  can  specify  the 
pathname  to  a specific  Web  server  by  choosing  option  4 below. 

1 . Exhaustive  search  (slow) 

2.  Search  in:  /usr,  /opt,  /etc,  /var  (moderate) 

3.  Search  the  common  Web  server  locations  (fast) 

4.  Don’t  search  (specify  Web  server  on  next  screen) 


Which  type  of  search  would  you  like  to  perform?  [2]  4 

Step  VII. 


Sun  Chili  ISoft  ASP  - Web  Server  Configuration 


No  Web  servers  have  been  detected.  As  options,  you  can  manually  specify  Web 
server  information  to  aid  in  detection,  direct  Setup  to  try  to  detect  more  Web 
servers,  or  delay  Web  server  configuration  until  another  time. 

1 . Specify  the  Web  server. 

2.  Attempt  to  auto-detect  more  Web  servers. 

3.  Do  not  configure  a Web  server. 


Which  configuration  option  would  you  like  to  perform?  [1]  1 

Step  VIII. 


Sun  Chili  ISoft  ASP  - User-specifed  Web  Server  Configuration 


Listed  below  are  the  types  of  Web  servers  to  which  this  version  of  Sun  Chili  ISoft 
ASP  will  install: 

1 . Apache 

2.  Netscape  / iPlanet 

3.  Zeus 

4.  Cancel  user-specified  Web  server  configuration. 


Which  Web  server  type  do  you  want  to  configure?  [1]  1 

BEFORE  REPLYING  TO  THE  NEXT  QUESTION,  DO  THE  FOLLOWING  STEPS 
FROM  ANOTHER  SERVER  CONSOLE: 

a)  check  if  your  version  of  Parallels  H-Sphere  Apache  server  is  different  from  the 
suported  bundle  version 

# /hsphere/shared/apache/bin/httpd  -v 

b)  if  it  is,  do  two  additional  steps: 

#mkdir  -p 

/hsphere/shared/casp/module/linux2_optimized/apache_1.3.{corresponding_numbe 

r}/eapi 
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#cp 

/hsphere/shared/casp/module/linux2_optimized/apache_{number_of_bundle_vesio 
n}/mod_casp2.so  \ 

/hsphere/shared/casp/module/linux2_optimized/apache_1 .3.{corresponding_numbe 
r}/eapi 

c)  return  to  the  installation  console. 

NOTE:  Regardless  of  this  fact,  you  may  be  able  to  build  your  own  module  that 
supports  this  version  of  Apache.  Refer  to  Sun  Chili ISoft  ASP  documentation  for 
information  on  building  your  own  module.  After  the  module  has  been  built,  proceed 
to  the  following  steps: 

(1)  # mkdir  -p 

/hsphere/shared/casp/module/linux2  optimized/apache  1.3.23/ea 
Pi 

(2) #  cp  <generated  build  dir>/mod  casp2 . so 

/hsphere/shared/casp/module/linux2  optimized/apache  1.3.23/ea 
pi 

(3)  Re-run  the  the  installer  by  executing  the  following  script: 

HASH (0x81b9b84) -{ asphome } / INSTALL/ install 

After  placing  the  file  into  the  created  module  directory,  the  installer  will  recognize  it 
as  a supported  Web  server  and  act  accordingly. 

Step  IX. 


Sun  Chili  ISoft  ASP  - Apache  Configuration 


Because  of  the  way  the  Apache  Web  server  works,  few  of  the  configuration 
questions  listed  below  can  be  answered  outright.  However,  wherever  possible, 
default  values  have  been  provided  for  some  of  the  questions. 

Note:  To  exit  Web  server  configuration,  type  ‘none’  for  the  listed  option. 


Enter  the  path  and  file  name  of  the  Apache  Web  server  configuration  file: 
[none]  /hsphere/shared/apache/conf/httpd.conf 


Enter  the  path  and  file  name  of  the  Apache  binary: 

[/hsphere/shared/apache/bin/httpd] 
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Step  X. 


Sun  Chili !Soft  ASP  - Web  Server  Configuration 


The  following  list  contains  all  currently  detected  Web  servers.  If  the  Web  server  for 
which  you  want  to  enable  ASP  support  appears  below,  enter  the  number  that 
corresponds  to  the  Web  server.  If  the  Web  server  is  not  listed,  you  can  manually 
specify  Web  server  information  to  aid  in  detection,  direct  Setup  to  try  to  detect  more 
Web  servers,  or  delay  Web  server  configuration  until  another  time. 

1 . Apache  Secure  Server 

Settings  file:  /hsphere/ shared/ apache/ conf /httpd.  conf 

Port:  80 

2.  Specify  the  Web  server. 

3.  Attempt  to  auto-detect  more  Web  servers. 

4.  Do  not  configure  a Web  server. 


Which  configuration  option  would  you  like  to  perform?  [1]  1 

Step  XI. 


Sun  Chili ISoft  ASP  - Web  Server  Verification 


Setup  has  automatically  detected  the  following  information  about  the  Web  server 
you  selected  on  the  previous  screen.  If  the  information  is  correct,  type  ‘y’  and  press 
Enter.  If  the  information  is  incorrect  type  ‘n’,  press  Enter,  and  then  select  ‘Specify 
the  Web  server’  from  the  menu. 

Web  server  information: 

Main  configuration  file:  /hsphere/ shared/ apache/ conf /httpd.  conf 
Binary:  /hsphere/ shared/ apache/bin/httpd 

Version:  1 .3.19 
Type:  Apache 
Port:  80 

Root:  /hsphere/shared/apache 


The  Web  server  information  is  correct  (y/n).  [n]  y 

Step  XII. 


Sun  Chili  ISoft  ASP  - Server  Configuration 


Setup  will  now  configure  the  Sun  Chili  ISoft  ASP  Server.  Unless  you  are  an 
experienced  Sun  Chili  ISoft  ASP  user,  it  is  strongly  recommended  that  you  use  the 
default  configuration  settings  (option  1,  below).  If  you  choose  the  custom 
configuration  option,  you  will  be  asked  to  specify  a number  of  settings.  For  detailed 
information  about  configuring  Sun  ChililSoft  ASP,  see  ‘Chapter  3’  in  the  product 
documentation. 

1 . Default  configuration. 

2.  Customize  configuration. 

3.  Choose  another  Web  server  to  install  to. 


Select  a configuration  option.  [1]  1 


Step  XIII. 

Chili ISoft  ASP  - Administration  Console  Installation 
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Setup  will  now  install  the  Sun  Chili  ISoft  ASP  Adminstation  Console.  Unless  you  are 
an  experienced  Sun  Chili  ISoft  ASP  user,  it  is  strongly  recommened  that  you  choose 
the  default  configuration  (option  1,  below).  If  you  choose  the  custom  configuration 
option,  you  will  be  asked  to  specify  a number  of  settings.  For  detailed  information 
about  configuring  the  Sun  ChililSoft  ASP  Adminstration  Console,  see  ‘Chapter  3’  in 
the  product  documentation. 

Note:  If  you  choose  the  ‘Default  configuration’  option,  the  username  and  password 
will  be  set  to  default  values.  To  protect  the  security  of  your  server,  you  should 
change  these  settings  immediately  after  installation.  For  more  infromation,  see  the 
product  documentation. 

1 . Default  configuration 

2.  Custom  configuration 


Select  a configuration  option  for  the  Administration  Console.  [1]  1 

Step  XIV. 


Sun  ChililSoft  ASP  - Administration  Console  Information 


Setup  has  finished  installing  the  Administration  Console.  To  configure  Sun  ChililSoft 
ASP,  you  can  connect  to  the  Administration 

Console  from  a URL  or  from  the  command  line,  as  shown  below.  For  more 
information  about  configuring  Sun  ChililSoft  ASP,  see  ‘Chapter  3’  in  the  product 
documentation.  It  is  a good  idea  to  print  this  page  for  future  reference. 


To  connect  from  a browser,  use  this  URL:  http:  //gargona .psoft : 5100 
To  start,  stop  and  add  users,  use  this  script:  /var/casp/admtool 
The  console’s  username  is:  admin 
The  console’s  password  is:  root 

To  continue,  press  Enter. 

Step  XV. 


Sun  ChililSoft  ASP  - Setup  Complete 


Sun  ChililSoft  ASP  has  been  successfully  installed!  Important  next  steps: 

- Read  the  README  file  that  came  with  Sun  ChililSoft  ASP.  This  file  contains  the 
latest  installation  and  application  notes. — Read  the  ‘Getting  Started’  section  in  the 
‘Sun  ChililSoft  ASP  Quick  Start  Guide.’  This  guide  provides  basic  information  about 
getting  started  with  Sun  ChililSoft  ASP,  and  points  you  to  additional  resources. — 
Take  a moment  to  register  this  product.  By  registering  you  will  be  eligible  for  30 
days  of  free  introductory  support.  Register  at:  http://www.chilisoft.com/register 


Summary  file:  /var/casp/logs/install  summary 

6.  If  the  installation  was  performed  correctly,  corresponding  Chili !ASP 
services  should  be  activated.  Use 
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# ps  -ax  | grep  casp 

Also,  check  the  httpd.conf  file  for  the  presence  of  additional  directives.  Use 

# grep  casp  /hsphere/shared/apache/conf /httpd.conf 

7.  If  all  is  OK,  copy  the  web  content  of  ASP  test  scripts  into  corresponding 
default  “DocumentRoot”  directory 

# cp  -Rp  /hsphere/shared/casp/caspsamp 
/hsphere/ shared/apache/htdocs/ 

8.  Check  the  operation  of  ASP  test  scripts  via  the  URL 
http://your_webserver_name/caspsamp 

9.  You  may  reinstall  Chili !ASP.  In  this  case,  you  need  to  execute  the 
/hsphere/shared/casp/unistall  script  prior  to  the  re-installation. 

NOTE:  It  is  advisable  to  avoid  restarting  Apache  when  installing  Chili ISoft  ASP  even  if 
suggested  so  by  the  installation  script. 


Installing  mocLperl 

This  guide  describes  the  installation  of  mod_perl  to  Parallels  H-Sphere  box. 

As  Apache  server  is  installed  without  mod_perl  support  during  Parallels  H-Sphere 
installation,  the  simplest  way  to  include  this  extension  is  through  building  mod_perl  as  a 
DSO  outside  the  Apache  source  tree  via  the  new  Apache  1 .3  support  tool  apxs 
(APache  extension). 

To  install  mod_perl: 

1.  Download  the  latest  mod_perl  source  and  documentation  from 
http://perl.apache.org.  Complete  documentation  may  be  found  at 
http://www.cpan.org/modules/bv-module/DB  File.  The  Apache- 
mod_perl_guide  installer  is  located  at  the  same  address. 

2.  Fulfill  the  following  build  steps: 

% tar  xzvf  mod  perl-x . xx . tar . gz 
% cd  mod_perl-x . xx 
% perl  Makefile. PL  \ 

USE_APXS=1  \ 

WITH  APXS=/hsphere/shared/apache/bin/apxs  \ 

EVERYTHING=1  \ 

[.  • •] 

% make  &&  make  install 


This  will  build  the  DSO  libperl.so  outside  the  Apache  source  tree  with  the  new 
Apache  1.3.x  support  tool  apxs  and  install  it  into  the  existing  Apache  hierarchy.  For 
example,  if  you  want  to  use  modjoerl  for  Web  server,  you  need  to  set 
WITH_APXS=/hsphere/shared/apache/bin/apxs.  Following  the  successful! 
installation  the  following  should  appear: 

a /hsphere/shared/apache/libexec/libperl . so  file 
b two  additional  directives  in  the 

/hsphere /local/ conf ig/httpd/httpd.  conf  file  (see  COnfig  file 
customization  from  Appendix  C of  Parallels  H-Sphere  Installation  Guide  for 
making  changes  into  httpd.conf): 
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LoadModule  perl  module  libexec/libperl . so 
AddModule  mod  perl.c 

3.  To  make  sure  that  mod_perl  works  correctly,  you  may  test  it  by  entering 
in  the  httpd.conf  file  a test  line  similar  to  the  one  below: 

Alias  /perl/  /path_to_directory/ 

PerlModule  Apache :: Registry 
CLocation  /perl> 

SetHandler  perl-script 
PerlHandler  Apache :: Registry 
Options  ExecCGI 
allow  from  all 
PerlSendHeader  On 
</Location> 

and  create  the  specified  above  perl  script  without  mentioning  the  perl  interpreter: 

/hsphere/ shared/ SiteS tudio/ public  html /perl /test . pi 

Next,  check  if  it  works  correctly  by  trying  out  the  link: 

http : / / some_url/perl/ test.pl 

NOTE:  If  you  plan  on  intensely  using  the  mod_perl  feature,  it  should  be  properly 
documented.  Download  and  install  the  documentation  at 
http://www.cpan.org/modules/bv-module/DB  File. 
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Mail  System 

This  chapter  describes  tasks  you  may  need  to  do  on  your  Parallels  H-Sphere  mail 
server(s). 

In  this  chapter: 

Understanding  Parallels  H-Sphere  Mail 131 

Choosing  Remote  Web  and  MySQL  Logical  Servers  for  Horde  Webmail  Frontend137 

Changing  Mail  Server  Roles 138 

Blocking  IPs  on  Mail  Servers 139 

Adding  Qmail  Settings  to  IP/Subnet 140 
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Configuring  Qmail 142 

Choosing  Remote  MySQL  Logical  Server  for  SpamAssassin 162 

SPF  and  SRS 163 

Updating  SpamAssassin  Rulesets  Automatically 166 

Migrating  Mail  Server/IP 1 71 

Moving  Mail  Domains 174 

Calculating  Mail  Traffic 175 

SpamGuard  Setup 178 
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Understanding  Parallels  H-Sphere  Mail 

Parallels  H-Sphere  mail  system  consists  of  the  following  blocks: 

1.  Parallels  H-Sphere  Mail  Package  (on  page  131):  includes  Qmail  SMTP 
server  with  a number  of  antispam/antivirus  and  other  extensions, 
vpopmail  POP3  server,  and  a number  of  other  applications. 

2.  Parallels  H-Sphere  Webmails  (on  page  132):  two  analogous  webmail 
applications,  SqWebMail  and  IMP  to  manage  mail  through  web 
interface.  System  administrators  can  choose  which  of  them  will  be 
offered  to  hosting  customers.  Apache  used  by  these  packages  is  the 
same  as  on  the  Parallels  H-Sphere  web  servers. 

3.  Parallels  H-Sphere  IMAP  Server  (on  page  135):  Courier-IMAP  server 
package.  It  is  included  into  Parallels  H-Sphere  mail  system  by  default. 

4.  Daemontools  (http://cr.yp.to/daemontools.html):  a collection  of  tools  for 
managing  UNIX  services  (such  as  ClamAV)  adapted  for  Parallels  H- 
Sphere. 

All  mail  system  components  are  installed  with  Parallels  H-Sphere  by  default. 

In  this  section: 
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Mail  Package 

Parallels  H-Sphere  mail  service  is  represented  by  mail  package  called  hsphere-mail- 
service-4-<vers/on>. 

Included  Software 

Parallels  H-Sphere  mail  service  includes  popular  mail  applications: 

■ hsphere-qmail  (http://www.qmail.org/top.html)  - message  transfer  utility  on  the 
modified  sendmail  protocol.  (See  Qmail  configuration  (on  page  142)  manual) 

■ hsphere-vpopmail  (http://www.inter7.com/vpopmail.html)  - virtual  mail  utility  on  the 
POP  protocol. 

■ hsphere-ucspi  (http://cr.yp.to/ucspi-tcp.html)  - tcp  server  and  related  utilities. 

■ hsphere-autorespond  - autoresponder. 

■ hsphere-ezmlm  (http://www.ezmlm.org/)  - mailing  list  manager. 

■ clamav  (http://clamdmail.sourceforqe.net/)  - qmail  antivirus  module. 

■ spamassassin  (http://www.spamassassin.org/index.html)  with  additional  perl 
modules  - qmail  antispam  module. 

Also,  ClamAV  and  SpamAssassin  require  MySQL  to  store  antivirus/antispam  data,  and 
they  run  under  the  supervise  utility  of  DJB  daemontools. 
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Webmails 

Parallels  H-Sphere  comes  with  such  webmail  clients  as: 

■ IMP  that  includes  horde  (http://www.horde.org/)  and  its  plugins: 

■ imp  (http://www.horde.org/imp/) 

■ kronolith  (http://www.horde.org/kronolith/) 

■ mnemo  (http://www.horde.org/mnemo/) 

■ nag  (http://www.horde.org/nag/) 

■ turba  (http://www.horde.org/turba/) 

■ SqWebMail  (http://www.inter7.com/sgwebmail/sgwebmail.html) 

■ ImapProxy  (on  page  135) 

The  default  client  is  IMP,  and  you  don’t  need  to  do  anything  to  use  it.  To  enable 
SqWebMail  over  IMP,  see  Enabling  SqWebMail  below. 

Horde  IMP  webmail  client  is  installed  on  each  mail  server.  In  earlier  versions,  it  was 
installed  on  one  of  the  Parallels  H-Sphere  web  servers. 

In  this  section: 
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Enabling  SqWebMail 

> To  set  SqWebmail  instead  of  IMP: 

1.  Log  into  the  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Open  the  hsphere  .properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 

3.  Comment  out  the  following  line: 

WEB_MAIL  = IMP 

4.  Restart  Parallels  H-Sphere  (on  page  41). 
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Setting  SMTP  Server  for  IMP 

IMP  configuration  is  written  in  the  ~httpd/htdocs/horde/ config/ conf  .php  file. 

IMP  is  configured  in  such  a way  that  it  uses  local  sendmail  as  SMTP  server  by  default. 

IMP  is  automatically  switched  to  use  external  SMTP  server  when  smdcheck  qmail 
parameter  (on  page  142)  is  enabled.  When  you  make  an  update  to  a version,  reenable 
the  parameter.  If  you  want  to  make  an  update  with  disabled  smdcheck  parameter, 
execute  the  following  script: 

/hsphere/shared/scripts/mailsend_type.sh  smtp 

Usage: 

mailsend_type . sh  [ smtp  | sendmail  ] 

> To  configure  IMP  to  use  external  SMTP  server,  modify  conf  .php  in  the 
following  way: 

1.  Change  the  mailer  type  to  smtp.  For  this,  change  the  line: 

$conf [' mailer ' ] ['type']  = 'sendmail'; 

to: 

$conf [' mailer ' ] ['type']  = 'smtp'; 

2.  Uncomment  the  following  line  and  specify  the  smtp  server: 

$conf [' mailer ' ] ['params']  = array  ('host'  => 

' smtp . example . com' ) ; 

where  smtp . example . com  should  be  a valid  smtp  server  name. 


Enabling/Disabling  ImapProxy 

ImapProxy  1 .2.4,  which  is  included  in  Webmail  package,  is  disabled  by  default. 
To  enable  it,  run  the  script: 

/hsphere/shared/ scripts/ imapproxy-init  set 

To  disable  ImapProxy  1 .2.4,  run: 

/hsphere/ shared/ scripts/ imapproxy-init  drop 


Localizing  Webmails 

The  /hsphere/local/ conf  ig/mail/ scripts/ add_locales  script  that  fixes  the 
Horde  localization  problem  on  TRUSTIX  OSs  is  included  into  the  package. 

Usage: 

add_locales  [ localel  locale2  . . . localeN  ] [ usage  ] [ list  ] 

Where: 

no  options  - adds  all  supported  by  HORDE  locales 
localel  ...  localeN  - adds  listed  locales 
list  - lists  all  supported  by  Horde  locales 
usage  - prints  this  message 

This  script  is  called  out  from  the  post-install  script  and  during  the  hsphere-webmails 
installation  adds  utf8  locales  only  for  Russian,  Italian,  French,  German,  Dutch,  Spanish, 
Portugese. 

To  add  the  languages  supported  by  Horde  but  not  installed  with  package  by  default, 
run  the  script  with  necessary  language  codes  (the  codes  should  be  delimited  by  a 
space).  For  instance,  to  add  Hungarian  and  Chinese,  run: 

/hsphere/local/config/mail/scripts/add_locales  hu_HU  zh_CN 

You  can  view  all  possible  language  codes  by  running: 

/hsphere/local/conf ig/mail/ scripts /add_locales  list 

Note:  you  need  to  have  the  package  glibc-iocaies  installed  on  the  server  for  the 
proper  work  of  the  script! 
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ImapProxy 

ImapProxy  component  is  by  default  included  into  Parallels  H-Sphere  Webmail 
package. 

ImapProxy  is  a daemon  that  proxies  IMAP  transactions  between  an  IMAP  client  and  an 
IMAP  server.  The  general  idea  is  that  the  client  should  never  know  that  it’s  not  talking 
to  the  real  IMAP  server.  The  only  thing  that  makes  this  a slightly  unique  Imap  Proxy 
server  is  that  it  caches  server  connections. 

The  ImapProxy  daemon  is  /hsphere/shared/bin/in.imapproxyd. 

The  startup  script  for  ImapProxy  daemon  is  /etc/init . d/imapproxy  for  Linux  and 

/ usr/ local/ etc/ rc  . d/ imapproxy . sh  for  FreeBSD. 

Usage  of  ImapProxy  daemon: 

Linux: 

/etc/init. d/imapproxy  [ start  | stop  | restart  | stat  | help  ] 

FreeBSD: 

/usr/local/etc/rc . d/imapproxy . sh  [ start  | stop  | restart  | stat  | 
help  ] 

where: 

■ start  starts  in.imapproxyd  service 

■ stop  stops  in.imapproxyd  service 

■ restart  stops  and  restarts  the  in.imapproxyd  service 

■ stat  displays  status  of  in.imapproxyd  service 

■ help  displays  help  message 

This  startup  script  uses  daemontools  (http://cr.vp.to/daemontools.html). 

ImapProxy  daemon  listens  to  144  port,  and  turns  to  143,  which  is  a default  courier- 
imap  port.  Imp  is  configured  to  turn  to  144  port,  so  imp  connects  to  courier-imap 
through  144  port  (through  ImapProxy  daemon). 

Package  includes  Statistic  tool  for  ImapProxy:  /hsphere/shared/bin/pimpstat. 
Usage  Of  /hsphere/shared/bin/pimpstat: 

/hsphere/shared/bin/pimpstat  -f  imapproxy . conf 

where  imapproxy.conf  is  the  configuration  file  for  ImapProxy  located  at 

/hsphere/local/ conf  ig/mail/ imapproxy  directory. 

IMAP  Server 

Parallels  H-Sphere  IMAP  Server  is  represented  with  two  components: 

■ courier-imap  (http://www.courier-mta.org/imap/) 

■ courier-authlib  (http://www.courier-mta.org/authlib/) 

Courier-IMAP  is  a standalone  IMAP  server  that  can  be  used  with  Parallels  H-Sphere 
Qmail  server  to  provide  IMAP  access  to  Maildirs. 

Courier-IMAP  is  included  into  Parallels  H-Sphere  mail  system  by  default. 
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IMAP  server  comes  with  IMAP  Before  SMTP  Authentication  support. 


In  this  section: 
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Starting  IMAP  Server 

Courier-IMAP  server  is  started  automatically  with  Parallels  H-Sphere  by  running  the 
following  commands: 

Linux: 

/sbin/chkconfig— level  2345  courier- imapd  on 
/ etc/rc . d/init . d/ courier- imapd  start 
/ etc/rc . d/init . d/courier-imapd-ssl  start 

FreeBSD: 

/usr/local/etc/rc . d/courier-imapd . sh  start 
/usr/local/etc/rc . d/courier-imapd-ssl . sh  start 


Note:  In  order  for  IMAP  SSL  to  start,  SSL  certificate  must  be  uploaded  through  the 
Control  Panel. 


Configuring  IMP  with  IMAP 

> To  configure  IMP  to  work  with  IMAP: 

1.  Log  into  the  CP  server  as  the  cpanel  user  (on  page  53). 

2.  Open  the  hsphere  .properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 

3.  Add  the  following  line: 

MAIL_PROTOCOL=imap 

4.  Restart  Parallels  H-Sphere  (on  page  41). 
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Choosing  Remote  Web  and  MySQL 
Logical  Servers  for  Horde  Webmail 
Frontend 


Parallels  H-Sphere  mail  logical  server  is  by  default  installed  on  a physical  box  together 
with  Web  and  MySQL  servers  on  the  same  box,  thus  Webmail  frontend  uses  Apache 
and  MySQL  on  the  same  server. 

It  is  made  possible  to  choose  an  alternative  remote  Web  and  MySQL  servers  for  Horde 
Webmail  frontend.  This  is  in  particular  important  for  the  implementation  of  load 
balanced  mail  cluster  (on  page  300)  where  it  is  required  that  Webmail  is  configured  to 
use  remote  Web  and  MySQL  servers.  Also,  now  you  can  configure  one  Horde  Webmail 
frontend  to  manage  multiple  mail  servers. 

> To  choose  remote  Web  and  MySQL  servers  for  Webmail: 

1.  Login  as  cpanei  user  (on  page  53)  and  set  the  following  property  in 

~cpanel / shi va/psof t_conf ig/h sphere .properties : 

EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  41)  to  apply  changes. 

important:  If  external_service_usage  is  not  set  or  is  not  true,  you  won’t  be 
able  to  choose  external  Web  and  MySQL  servers  for  Webmail! 

2.  In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  mail  logical  server,  and  Choose  Unix  Hosting  server  for  Horde 
under  Mail  Server  Additional  Options. 

3.  Proceed  to  the  selected  Web  (Unix  Hosting)  logical  server  settings  in 
the  E.Manager->  Servers ->  L.Servers  list  and  select  a remote  MySQL 
server  for  Horde  database  from  the  Choose  External  Horde  DB  Server 
dropdown  menu . 

4.  Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
updater  with  the  hspackages  reconfig  option: 

hspackages  reconf ig=f rontend 

Note:  Regular  Parallels  H-Sphere  update  automatically  includes  the  reconfig 
option.  However,  for  best  performance  we  recommend  running  Parallels  H-Sphere 
updater  with  this  option  separately. 

More  about  Parallels  H-Sphere  updater  read  in  the  Update  Guide. 

5.  To  move  Horde’s  Web  and  DB  content  to  respective  remote  Web  and 
MySQL  logical  server  locations,  run  the  following  script  on  the  source 
box: 

/hsphere/pkg/ script s/uprocedures/ dbs_content  -h 

Usage: 

dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 

dbtype:  horde  or  spamassassin  or  phpmyadmin 


138  Mail  System 


ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the  corresponding 
mail  logical  server 

password:  this  option  is  required  only  in  the  case  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding  mail 
logical  server 


Changing  Mail  Server  Roles 

This  document  explains  how  to  have  incoming  mail  queued  on  a relay  mail  server  while 
the  master  mail  server  is  down  or  otherwise  unable  to  receive  mail. 

For  this,  you  need  to  do  two  things: 

1 . Mark  the  backup  mail  server  as  relay. 

2.  Allow  relaying  in  the  plan  so  that  users  can  use  the  relay  server. 

Every  active  mail  server  can  be  either  relay  or  master+relay. 

■ master+relay  means  that  (1 ) new  mail  domains  will  be  created  on  this  server  and 
(2)  the  server  will  receive  mail  for  domains  on  other  mail  servers. 

■ relay  (secondary  queue  server)  means  that  new  domains  won’t  be  created  on  this 
server,  but  the  server  will  relay  mail  for  domains  on  other  servers. 

By  default,  all  mail  servers  are  set  as  master  and  relay,  which  is  the  recommended 
configuration. 

Note:  If  you  do  not  want  to  use  a server  with  new  domains  (neither  host  new  domains 
nor  relay  mail  for  them),  make  it  unavailable  for  signup. 

Important:  It  is  highly  recommended  to  move  static  mail  relays  from  a Web  server  to  a 
dedicated  mail  relay  server,  as  Web  content  on  the  same  server  with  mail  relay  may 
become  a target  for  spambot  attacks! 


> To  change  the  role  of  a mail  server  at  the  system  level: 

1.  Log  into  the  control  panel  as  admin. 

2.  Go  to  E.Manager->  Servers  ->  L.Servers  and  select  the  mail  server. 

At  the  bottom  of  the  form  that  appears,  choose  server  role  from  the  drop-down  box. 
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You  can  allow  or  disallow  relaying  mail  for  a specific  plan.  With  relaying  allowed,  mail 
to  accounts  under  this  plan  will  be  queued  on  other  servers  when  their  mail  server  is 
down. 

1.  Log  into  the  control  panel  as  admin. 

2.  Select  Plans->Manage. 

3.  Choose  the  plan. 

4.  On  the  first  step  of  the  wizard,  check  Include  for  Mail  Relay. 

F — — 


If  mail  relays  are  allowed  in  the  plan,  users  can  choose  a relay  server  for  a specific 
account  in  their  User  control  panel.  If  the  server  is  down,  mail  for  this  account  will  be 
queued  on  this  relay  server. 

1.  Log  into  this  account. 

2.  Go  to  Mail  Info  menu. 

3.  Turn  Mail  Relay  on. 

This  will  add  an  MX  record  for  the  server  that  was  set  as  relay. 


Blocking  IPs  on  Mail  Servers 

To  fight  spam  or  block  unwanted  emails,  you  can  block  specific  IPs  from  sending  you 
mail.  The  incoming  messages  from  this  IP  will  bounce  back  to  the  sender. 

> To  deny  relay  to  specific  IP: 

1 . Go  to  E.Manager  ->  Servers  - > Mail  Servers: 

2.  At  the  bottom  of  the  page  choose  mail  server  from  the  drop-down  box. 

3.  Enter  necessary  IP/subnet. 

4.  Enter  note,  if  necessary,  and  click  the  Add  button. 

The  blocked  IP  will  appear  in  the  Mail  Server  Relays  section 

You  can  remove  the  blocked  IP  from  the  list  at  any  moment  by  clicking  the  Trash 
icon  on  the  right. 
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Adding  Qmail  Settings  to  IP/Subnet 

> To  add  mail  relay  and  other  Qmail  settings  to  a chosen  IP/subnet. 

1 . Go  to  E.Manager  ->  Servers  - > Mail  Servers: 

2.  Click  the  Add  button  and  fill  in  the  form: 

■ Choose  mail  server  from  the  drop-down  box 

■ Enter  necessary  IP/subnet  and  a comment,  if  necessary, 

■ Set  Qmail  parameters.  Some  of  them  are  checked  to  use  default  value.  To  enter 
custom  value,  uncheck  it. 

Note:  To  deny  mail  relay,  go  to  Blocking  IP  (on  page  139). 

3.  Click  Submit.  The  record  will  appear  in  the  Mail  Relays  section 

You  can  remove  the  record  from  the  list  at  any  moment  by  clicking  the  Trash  icon  on  the 
right. 


Bouncing  Mail 

When  a mail  server  accepts  a message  and  later  decides  that  it  can’t  deliver  the 
message,  it  is  required  to  send  back  a bounce  email  to  the  sender  of  the  original 
message.  These  bounce  emails  are  often  misdirected. 

This  document  outlines  the  correct  configuration  of  mail  server  where  mail  bouncing 
should  always  work.  Mail  servers  are  by  default  configured  in  accordance  with  this 
scheme. 

Mail  bouncing  policy  implies  the  following  three  independent  strategies: 

1.  Separate  bounce  IP 

2.  Processing  error  responses 

3.  Bounced  mail  delivery 

See  Qmail  bounce  parameters  (on  page  142)  for  details. 


In  this  section: 
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1 . Separate  IP  for  Sending  Bounced  Mail 

Separate  IP  for  sending  bounced  mail  allows  sending  bounces,  but  isolates  them  to  a 
different  IP  address  (so  that  spamcop  can  block  them  without  blocking  other  mail). 

How  to  configure: 

The  respective  bounce  IP  network  alias  must  be  up.  Then,  specify  the  bounce  IP  in  the 

/var/ qmail/ control /bound ngip  file  and  restart  qmail  Or  set  the  bouncingip 

parameter  in  the  Qmail  Settings  form  in  the  administrator  CP. 

After  that,  restart  qmail. 


2.  Processing  Error  Responses 

There  are  2 main  error  status  groups: 

■ temporary  errors:  delivery  of  such  messages  is  done  during  queue  lifetime  period 

■ permanent  errors:  after  the  first  delivery  attempt  the  message  is  queued  as  a 
bounce  message 

In  many  cases  temporary  error  status  is  inadequate.  For  example,  the  absence  of 
mailbox  or  quota  overlimit  is  sometimes  considered  by  a remote  box  as  a temporary 
error  - as  a result,  the  message  may  remain  in  the  queue  during  lifetime  period. 

hsphe  re -mail -service  packages  adds  a possibility  to  configure  3 additional 
states: 

1 . Consider  temporary  errors  as  permanent  errors  for  local  mail  delivery 

2.  Consider  temporary  errors  as  permanent  errors  for  remote  mail  delivery 

3.  Consider  temporary  errors  as  permanent  errors  for  local  and  remote  mail  delivery 

How  to  configure: 

Set  the  temperror  parameter  in  /var/qmail/ control/options: 

■ temperror=0  or  absent  (default)  - common  behavior; 

■ temperror=1  - consider  temporary  errors  as  permanent  errors  for  local  mail 
delivery; 

■ temperror=2  - consider  temporary  errors  as  permanent  errors  for  remote  mail 
delivery; 

■ temperror=3  - consider  temporary  errors  as  permanent  errors  for  local  and  remote 
mail  delivery. 
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3.  Bounced  Message  Delivery 

Bounced  message  delivery  is  performed  in  3 ways: 

1.  Simple  bouncing:  message  is  bounced. 

2.  Double  bouncing:  message  is  sent  to  a predefined  location. 

3.  Triple  bouncing:  - message  is  discarded. 

Current  mail  configuration  allows  regarding  double  bounce  as  triple  bounce.  We  have 
added  a possibility  to  configure  common  bounce  delivery  as  double  bouncing  or  even 
triple  bouncing.  This  may  be  useful  when  queue  grows  big  and  common  message 
delivery  suffers.  However,  in  many  cases  this  configuration  is  not  recommended  and 
should  be  applied  only  in  critical  situations. 

How  to  configure: 

Set  the  strictbounce  parameter  in  /var/qmaii/ control/ options  if  necessary: 

■ strictbounce=1  - consider  simple  bounce  as  double  bounce 

■ strictbounce=2  - consider  simple  bounce  and  double  bounce  as  triple  bounce 


Configuring  Qmail 

Parallels  H-Sphere  offers  enhanced  Qmail  SMTP  server  configuration.  Most 
enhancements  have  been  added  to  fight  spam  at  the  server  level. 


In  this  section: 


Antivirus  and  Antispam  Filters  (Spam Assassin  and  ClamAV) 143 
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Syslog  Facility/Level  Configuration  For  rblsmtpd 158 

SMTP  Log 158 
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Qmail-spp  Support 160 

Qmail  TLS  Support 161 

Integrated  Plugins 161 
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Antivirus  and  Antispam  Filters  (SpamAssassin  and 
ClamAV) 

Qmail  incorporates  SpamAssassin  and  ClamAV  filters  at  the  server  level.  It  uses  an 
improved  qmail-queue  patch  concept,  where  the  use  of  the  QMAILQUEUE  variable  is 
replaced  with  checking  recipient  addresses  against  the  clamavciients  and 
spamdclients  databases  (see  the  drawing).  Parallels  H-Sphere  users  can  add  their 
mail  addresses  to  the  database  to  have  them  checked  for  spam  and  viruses.  User- 
defined  antispam  preferences  are  stored  in  a MySQL  database. 

Mail  is  filtered  by  standalone  clamd  and  spamd  services.  We  had  to  get  rid  of  the 
Qmail-Scanner  perl  wrapper,  because  it  is  rather  heavy  and  unreliable  for  high  load 
SMTP  servers.  Instead,  we  use  clamdmail  software,  http://clamdmail.sourceforqe.net/, 
which  is  fast  and  adapted  to  working  with  clamd  and/or  spamd. 
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In  this  section: 


Updating  Virus  Patterns 144 

Enabling  Antivirus  and  Antispam 144 

Configuring  ClamAV  and  SpamAssassin  at  the  Server  Level 144 

Restarting  ClamAV  and  SpamAssassin 144 

Updating  ClamAV  Database 145 

User  Settings 145 


Updating  Virus  Patterns 

Mail  server  cron  has  a script  that  updates  virus  patterns  every  day  at  12AM.  You  can 
manually  change  the  timing  of  the  cron. 

Enabling  Antivirus  and  Antispam 

ClamAV  and  Spamassasin  have  been  added  to  Parallels  H-Sphere  as  resources,  and 
can  be  enabled  and  disabled  from  the  control  panel: 

1.  Global  Settings.  In  Plans  ->  Globals,  check  Antispam  and  Antivirus  and 
click  Submit  Query. 

2.  Plans.  In  Plans  ->  Plans  select  the  plans  where  you  would  like  to  enable 
spam  and  virus  protection.  On  the  first  page  of  the  wizard,  enable 
Antispam  and  Antivirus.  Optionally,  set  prices  for  these  resources  on  the 
subsequent  steps. 


Configuring  ClamAV  and  SpamAssassin  at  the  Server  Level 

■ ClamAV:  edit  file  /hsphere/local/conf  ig/mail/clamav/ clamav . conf . 

The  format  and  options  of  this  file  are  fully  described  in  the  clamav.conf(5)  manual. 
Remember  - you  must  remove  the  “Example”  directive.  Be  careful  not  to  change  the 
values  of  LocalSocket  and  TCPSocket. 

■ SpamAssassin:  edit  file 

/hsphere/ local/ conf ig/mail/spamas sas sin /local . cf  as  suggested  in 
Spamassassin  documentation 

(http://www.spamassassin.org/doc/Mail  SpamAssassin  Conf.html).  Note  that 
external  modules  like  Bayesian  rules,  razor2,  dec,  and  pyzor  are  not  included,  so 
please  be  careful  not  to  enable  related  options. 


Restarting  ClamAV  and  SpamAssassin 

See  Restarting  Services  (on  page  39). 
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Updating  ClamAV  Database 

Each  hour  cron  updates  ClamAV  antivirus  databases.  Execute  crontab  -l  to  see  the 
list  of  cron  tasks  for  a mail  server.  The  following  line  indicates  that  ClamAV  database  is 
updated  each  hour: 

0 * * * * /hsphere/shared/bin/f reshclam— quiet 

ClamAV  database  update  is  configured  in 

/hsphere/local/ config/mail/ clamav/f reshclam. conf. 

User  Settings 

ClamAV  and  Spamassasin  settings  can  be  configured  per  maildomain  and  individual 
mailbox.  Please  see  Parallels  H-Sphere  User  Guide  for  details. 

Integrated  Antispam  Addons 

Besides  SpamAssassin,  Parallels  H-Sphere  Qmail  includes  a series  of  third  party  and 
in-house  antispam  addons: 

■ Fehcom  Spamcontrol  patch,  http://www.fehcom.de/qmail/spamcontrol.html,  (based 
on  the  spamcontrol-2.4.17  release)  provided  with  opportunity  to  switch  whitelist 
extensions  on  and  off  dynamically 

■ qmail-smtpd  badmailfrom-unknown  addon, 
http://www.lamer.de/maex/creative/software/qmail/103-bmfunk/ 

■ Qmail  patch,  http://www.qmail.org/biq-concurrencv.patch,  to  allow  Qmail  to  use  a 
concurrency  greater  than  240 

■ doublebounce-trim  patch,  http://www.qmail.org/doublebounce-trim.patch,  to  discard 
doublebounces  without  queuing  them 

■ Jose  Luis  Painceira’s  patch  that  deletes  the  body  of  bouncing  messages 
(http://qmail.org/qmail-send.mimeheaders.tar.qz).  This  patch  is  based  on  Fred 
Lindberg’s  patch  that  preserves  the  MIME-ness  of  bouncing  MIME  messages 
(http://www.ezmlm.org/pub/patches/qmail-mime.tqz) 

■ qmail-maildir++.patch  (from  Vpopmail  distribution) 

■ Parallels  addon  that  checks  if  the  sender’s  address  in  POP-before-SMTP 
authentication  is  local  and  the  recipient’s  address  is  remote; 

■ Parallels  addon  that  checks  if  domain  name  in  the  sender’s  address  matches  the 
domain  name  used  in  SMTP  authentication. 

■ Andre  Oppermann’s  ext-todo  patch,  http://www.nrq4u.com/qmail/ext  todo- 
200301 05.patch,  which  solves  the  ‘silly  qmail  syndrome’.  That’s  where  qmail 
spends  more  time  processing  incoming  email  than  scheduling  deliveries. 

■ big-DNS  patch,  http://www.ckdhr.com/ckd/qmail-103.patch,  which  fixes  oversize 
DNS  packet  problem. 

■ Modified  version  of  Qmail  chkuser  0.6  patch  (http://www.shupp.org/)  that  checks  if 
the  vpopmail  recipient  is  valid  before  accepting  the  message. 
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Qmail  Server  Settings 

Default  Qmail  server  settings,  including  antispam  options,  can  be  configured  in  the 
admin  control  panel  in  the  E. Manager/Servers/Mail  Servers  menu. 

> To  configure  Qmail  settings: 

1 . Select  Mail  Servers  from  the  E. Manager  ->  Servers  menu : 


2.  Click  the  Action  icon  in  the  Mail  Server  Settings  section: 
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3.  Edit  qmail  settings  following  on-screen  explanations  and  click  Submit: 
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IMPORTANT: 

Values  can  be  of  three  types: 

■ Text:  can  be  either  a line,  like  @1 2.34.56.78,  or  a list,  for  example  a list  of 
addresses  in  badmailfrom. 

badmailfrom  is  the  file  that  containts  a list  of  senders  mail  isn’t  accepted  from. 

■ Number,  like  1 000  in  databytes. 

databytes  is  the  file  that  contains  the  maximum  allowed  size  of  a message. 

■ Boolean,  like  0 or  1 in  smtpauth. 

0 disables  SMTP  Auth,  1 enables  it. 

Note:  0 is  also  set  by  default  if  the  corresponding  control  file  is  absent. 

Thus,  for  example,  if  you  have  to  enable  SMTP  Auth,  you  create/modify  the 
/ var/ qmaii/ control/ smtpauth  control  file  and  put  1 in  it.  To  disable  SMTP  Auth, 
put  0 in  the  control  file  or  just  delete  the  control  file. 

Also,  text  values  may  contain  patterns:  wildcard  expressions  to  set  the  range  of  emails, 
domains  and  IPs  for  filtering  rules. 

Control  characters  in  patterns: 

■ Exclamation  mark  (!):  allows  you  to  INCLUDE  particular  clients/addresses  by 
simply  putting  an  exclamation  mark  (!)  as  first  character  in  the  line. 

■ Asterisk  (*):  General  pattern  matching  character;  one  or  more  preceding. 

■ Question  Mark  (?):  Match  zero  or  one  preceding. 

■ Backslash  (\):  Literal  expression  of  following  character,  eg.  \[. 

■ Match  one  from  a set  ([...]):  i.e.  [Ff][Aa][Kk][Ee]  matches  FAKE,  fake,  FaKe, 
FAKe  etc. 

Qmaii  settings: 

■ tcpsessioncount:  the  number  of  concurrent  SMTP  connections.  Default:  40. 
After  setting  this  parameter,  Qmaii  restart  (on  page  44)  is  required. 

■ concurrencyremote:  the  number  of  qmail-send  processes  of  message  delivery 
to  remote  addresses.  Default:  100.  Max:  500.  If  Max  is  exceeded,  Max  value  is  set. 

■ concurrency  local:  the  number  of  qmail-send  processes  for  message  delivery  to 
local  addresses.  Default:  50.  Max:  500.  If  Max  is  exceeded,  Max  value  is  set. 

■ databytes:  maximum  size  of  a message.  Default:  0 (unlimited). 

■ queuelifetime:  the  message  queue  lifetime  in  seconds.  Default:  604800  (1 
week). 

■ bouncef  rom:  the  email  user  messages  are  bounced  from. 

Default:  MAILER-DAEMON; 

■ maxrecipients:  maximum  number  of  recipients  in  the  “TO:”,  “CC:”,  and  “BCC” 
fields.  Defaults  (unlimited). 

■ maxwrongrcpt:  maximum  number  of  wrong  recipients  in  the  envelope.  Default:  0 
(unlimited). 

■ timeout smtpd:  TCP  connection  timeout  in  seconds.  Default:  1200. 

■ newline:  accept  or  reject  mail  from  mail  user  agents  (MUA)  that  send  commands 
without  CR  (carriage  return).  Default: 0 (disabled); 
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■ strip  single  quotes:  enable  or  disable  stripping  single  quotes  (referred  to  in  the 
spamcontrol  manual  as  the  feature  that  may  cause  unpredictable  results).  Default: 
0 (disabled); 

■ lowercase:  enable  or  disable  conversion  of  mail  address  to  lowercase;  it  may  be 
useful  in  filtering  patterns,  for  case-sensitive  rules.  Default:  0 (disabled). 

■ badmailf rom:  list  of  sender  addresses  whose  emails  will  be  rejected.  A line  in 
badmailfrom  may  be  of  the  form  @host,  meaning  every  address  at  host. 

Default:  the  badmailfrom  file  is  absent  (all  sender  addresses  are  allowed);  See  also 

splithorizon. 

■ badmailpatterns:  the  same  as  standard  badmailfrom  but  with  patterns. 
Example: 

*@ear thlink.net 
! fred@earthlink.net 

f 0-9]  [0-9]  [0-9]  [0-9]  [0-9] @ [0-9]  [0-9]  [0-9]  .com 
answerme@save* 

%; 


Default:  the  badmailpatterns  file  is  absent  (all  sender  addresses  are  allowed);  See 
also  splithorizon. 

■ badmailf rom-unknown:  if  the  domain  part  of  sender’s  address  matches  a host  in 
this  list,  qmail  checks  if  sender’s  IP  has  a PTR  record.  Example: 
http://www.lamer.de/maex/creative/software/qmail/103-bmfunk/badmailfrom- 

unknown.  Default:  the  badmailf  rom-unknown  file  is  absent  (reverse  DNS  check 
is  disabled  for  all  IPs). 

■ badhelo:  filter  HELO/EHLO  sequence  issued  by  SMTP  client;  See  also 
splithorizon. 

■ badrcptto:  list  of  recipient  addresses  for  which  all  mail  is  blocked.  A line  in 
badrecipient  may  be  of  the  form  @host,  meaning  every  address  at  the  host. 

Default:  the  badrcptto  file  is  absent  (no  recepient  addresses  are  blocked). 

■ badrcptpatterns:  the  same  as  badrcptto  but  with  patterns.  It  allows  qmail-smtpd 
to  reject  SPAM  E-Mail  including  the  signature 

\[dd.dd.dd.dd\] 

in  the  badrcptpatterns  file,  where  dd.dd.dd  is  the  IP  address  in  brackets.  Default 
the  badrcptpatterns  file  is  absent  (no  recipient  addresses  are  blocked). 

■ biackhoiedsender:  the  same  as  badmailpatterns  but  quits  the  session 
immediately  even  if  quitasap  is  disabled. 

■ relayclients:  list  of  IP  addresses  of  clients  allowed  to  relay  mail  through  this 
host.  Addresses  in  relayclients  may  be  wildcarded: 

192.168.0. 1: 

192.168.1. : 

Default:  the  relayclients  file  is  absent  (all  client  IPs  are  allowed  to  relay  mail  via  this 
host). 

■ relaydomains:  list  of  host  and  domain  names  allowed  to  relay  mail  through  this 
host.  This  is  an  additional  mail  relay  check  by  the  domain  name,  in  case  if  relay  via 
the  tcp.cdb  static  relay  database  is  forbidden.  More  on  mail  relays  read  in  Parallels 
H-Sphere  Service  Administrator  Guide,  SMTP  Mail  Relays  section. 

Addresses  in  relaydomains  may  be  wildcarded: 

heaven . af .mil : 

. heaven .af.mil: 
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Default:  the  relaydomains  file  is  absent  (all  domains  are  allowed  to  relay  mail). 

■ relaymailf  rom:  list  of  senders  (“Mail  From:”)  allowed  to  relay  independently  even 
if  open  relay  is  closed.  Entries  in  relaymailfrom  can  be  E-Mail  addresses,  or  just  the 
domain  (with  the  @ sign).  Unlike  relaydomains,  native  addresses  should  be 
entered.  Examples: 

j oeblow@domainl . com 
@domain2 . com 

Default:  the  relaymailfrom  file  is  absent  (no  senders  are  allowed  to  relay 
independently). 

Important:  For  antispam  security  reasons,  we  strongly  recommend  not  to  add  this 
parameter  to  SMTP  configuration. 

■ quitasap:  enables  (1 ) or  disables  (0)  quitting  of  SMTP  session  immediately  if  one 
of  the  above  rules  works.  Default:  0 (no  quitting).  Enabling  this  option  is 
recommended  only  in  case  of  spam  attacks  or  huge  spam  traffic  to  your  server.  If 
working,  quitasap  breaks  SMTP  connection  if  at  least  one  of  the  following 
parameters  is  enabled,  the  result  of  its  check  being  negative: 

■ SPF  check 

■ smdcheck 

■ mfdnscheck 

■ no  openrelay  for  sender  IP 

■ badmailfrom 

■ badmailfrom-unknown 

■ badrcptto 

■ userchk 

■ maxrecipients 

■ smtpauth 

■ antivirus 

■ antispam 

■ badhelo 

■ helodnscheck 

Use  the  quitasap  option  with  precaution  as  breaking  of  SMTP  connection  is  contrary 
to  the  requirements  of  correct  SMTP  server  operation. 

■ tarpitcount:  the  number  of  recipients  after  which  qmail  switches  on  delay  before 
sending  the  message  to  the  next  portion  of  recipients. 

Default:  0 (no  tarpitting); 

■ tarpitdelay:  the  time  in  seconds  of  delay  to  be  introduced  after  each 
subsequent  RCPT  TO:.  Default:  5. 

■ mfdnscheck:  enables  (1)  or  disables  (0)  DNS  check  of  domain  name  in  sender’s 
address.  If  enabled,  no  local  domain  check  is  performed. 

Default:  0 (disabled); 

■ nomfdns check:  list  of  domain  names  that  aren’t  checked  for  existence.  The  list 
has  the  same  format  as  for  relaymailfrom.  Default:  the  nomfdnscheck  file  is  absent 
(if  mfdnscheck  is  enabled,  all  domains  are  checked  for  existence); 

■ helodnscheck:  in  a manner  similar  to  mfdnscheck,  performs  check  for 
PIELO/EPILO  smtp  commands  instead  of  RCPT  TO:.  See  also  splithorizon. 
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■ splithorizon:  if  1,  helodnscheck,  badhelo,  badmailfrom,  and  badmailpatterns 
checks  for  SMTP  sessions  with  open  relay  mfdnscheck  are  not  performed. 

■ userchk:  enables  (1 ) or  disables  (0)  check  that  the  vpopmail  recipient  is  valid 
before  accepting  the  message.  Default:  0 (disabled); 

■ smdcheck:  allows  only  local  domains  in  the  MAIL  FROM  address  if  mail  is  sent 
remotely.  If  the  option  is  enabled,  SMTP  is  used,  otherwise  - Sendmail  is. 

Default:  0 (any  sender  address  is  allowed). 

■ authsender:  if  set  to  1 , it  requires  the  domain  name  in  user  address  during  SMTP 
authentication  to  coincide  with  the  domain  name  in  the  MAIL  FROM  address  field, 
a By  default:  ‘0’  if  smtpauth  parameter  is  OFF. 

■ By  default:  ‘2’  if  smtpauth  parameter  is  ON. 

Note:  value  ‘2’  is  used  as  additional  procedure  providing  correct  traffic  calculation  in 
case  of  dynamic  open  relay.  In  this  case , instead  of  recording  mail  envelop  sender 
domain,  traffic  log  records  the  domain  used  in  SMTP  authentication). 

■ rbihosts : RBL  (Remote  Black  List)  database  hosts.  Example: 

dnsbl.njabl.org 
spamguard . leadmon . net 

Allowed  anti-RBL  source  addition  (http://cr.yp.to/ucspi-tcp/rblsmtpd.html).  Format  of 
anti-RBL  source  : a : domainname . Default : the  rbihosts  file  is  absent  (RBL  check 
is  disabled:  no  external  RBL  databases  is  being  checked). 

Note  1 : Parallels  Pi-Sphere  Qmail  MTA  is  built  with  “A”  record  patch,  so  it’s  possible 
to  enable  DNSBL,  which  doesn’t  support  “TXT”  DNS  records.  For  instance,  Trend 
Micro  Network  Reputation  Services  DNSBL 
(http://us.trendmicro.com/us/products/enterprise/network-reputation- 
services/index.html).  You  can  enable  its  support  via  Mail  Service  Settings  in  the 
Admin  CP.  At  the  moment,  you  can  do  it  by  adding  the  string: 

"activationcode . r .mail-abuse . com: blocked  using  Trend  Micro 
RBL+,  please  see  http://www.mail-abuse.com/cgi- 
bin/lookup?ip  address=%IP%" 

Note  2: 

a Quotation  marks  are  necessary, 
b For  commercial  RBL,  like  Trend  Micro  RBL+ 

(http://us.trendmicro.com/us/products/enterprise/network-reputation- 

services/index.html),  after  the  service  is  rendered,  the  corresponding  value 
Should  be  set  instead  Of  activationcode. 

■ qmaiispp : Enables  Qmail  plugin  support.  Default:  0 (disabled). 

■ f lagf ailciosed:  Always  consider  dns  lookups  failure  as  a temporary  error,  451 . 
Default:  0 (disabled). 

■ f lagrbibounce:  Consider  RBL  error  status  code  as  a fatal  (553),  instead  of 
default  policy,  temporary  error  (451).  Default:  0 (disabled). 

■ strictheiocheck  parameter  (options  file,  disabled  by  default),  which  considers 
PIELO  command  obligatory. 

■ chksignature : (options  file),  which  provide  badsignatures  filtering  for  mail 
resources  with  enabled  antivirus  check.  Default. ’0  (disabled). 

■ chkioadertype:  (options  file),  which  provide  badloadertypes  filtering  for  mail 
resources  with  enabled  antivirus  check.  Default.  0 (disabled). 

Both  chksignature  and  chkioadertype  include  a wire-speed  filtering  of  E-Mails 
containing  BASE64  encoded  attachments  with  about  99,5%  efficiency: 
http://www.fehcom.de/gmail/docu/virus  2004.pdf 


Note:  chksignature  provides  a 

Note:  chkloadertype  provides  a 

robust  MIME  type  identification. 

high  efficient  and  unique  Loader 

Particular  MIME  types  can  be 

type  recognition.  Though  this 

added  on-the-fiy  (based  on  the  idea 

procedure  is  more  heavy,  than 

of  Russell  Nelson’s  (and  Charles 

signature  check  and  is  less 

Cazabon’s)  to  filter  Windows 

recommended.  Predefined 

executables  attached  as  BASE64 

loadertype  check  is  oriented  on  the 

encoded  MIME  parts  in  the  E-  Mail. 

Kernel32.dll  search  (specific  Loader 

Included  the  following  signatures, 

types  for  the  Windows  OS  are 

which  detect  specific  common, 

included  in  control/badloadertypes): 

double  and  triple  Base  64  Windows 

Mi  5 kb 

Executable  (control/badsignatures): 

MzluZ 

TVqQAAMAA 

MyLmR 

TVpQAAIAA 

MyLkR 

TVpAALQAc 

Mi5ET 

TVpyAXkAX 

TVrmAU4AA 

TVrhARwAk 

TVoFAQUAA 

TVoAAAQAA 

TVoIARMAA 

TVouARsAA 

TVrQAT8AA 

TVrvAEQAe 

UEsDBAoAA 

VFZxUUFBT 

VkZaeFWR 

ZGItIGZpb 

My51e 
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Note:  The  list  of  signatures  is  static,  not  configurable  via  CP  interface.  If  you  want 
to  add  something,  you  should  edit  the  corresponding  control  files:  badloadertypes 
and  badsignatures. 

■ sms:  Restriction  of  Max  messages  for  one  email  value  for  Mail  SMS  resource  (Max 
value:  3).  Default:  3. 

■ spamgiobai:  Antispam  check  of  all  incoming  mail.  Default:  0 (disabled). 

■ clamgiobai:  Antivirus  check  of  all  incoming  mail.  Default:  0 (disabled). 

■ skipcachk:  ClamAV  (Antivirus  Filter)  check  restriction.  Default:  0 (disabled). 

■ skipsachk:  Spamassassin  (AntiSpam  Filter)  check  restriction.  Defaults 
(disabled). 

■ periplimit:  enter  the  number  of  simultaneous  SMTP  connections  from  the  same 
IP. 

■ noathost:  demands  fully  qualified  domain  email  address  in  RCPT  TO  and  MAIL 
FROM  smtp  commands.  Default:  0 (disabled).  If  you  enable  this  parameter,  you  will 
never  get  reject/bounce  messages,  or  return  receipts,  and  you  may  get  other  mail 
server  admins  upset  at  you  if  they  have  to  deal  with  your  bounce  messages.  Since 
this  is  contrary  to  the  requirements  of  correct  SMTP  server  operation  (Mailservers 
are  required  by  RFC1 123  5.2.9  to  accept  mail  from  “<>”),  use  noathost  parameter 
with  precaution. 

■ sanetcheck:  enables/disables  network  check  for  SpamAssassin.  Default:  0 
(disabled).  By  default,  SpamAssassin  performs  only  local  tests.  By  enabling  this 
parameter  you  can  also  enable  network  tests  for  SpamAssassin,  such  as 
DCC_CPIECK  (Distributed  Checksum  Clearinghouse  is  an  anti-spam  content  filter), 
URIDNSBL  (look  up  URLs  found  in  the  message  against  several  DNS)  etc.  These 
network  test  use  internet  resources.  Network  tests  must  be  set  in  the  additional 
configuration  file 

(/hsphe  re /local/  con  fig/mail/  spamassassin/ custom,  cf).  A path  to  this 
file  is  set  via  the  include  directive  of  the  main  SpamAssasin  local. cf  file.  Use  this 
additional  configuration  file  for  plugins  and  options  of  SpamAssassin. 

■ spamdchiidren:  specifies  the  number  of  forked  spamd  child  processes.  Default: 
10.  We  recommend  to  increase  it  for  servers  with  large  number  of  smtpd 
connections. 

■ rcptdns checks:  allows  only  existing  mail  domain  names  of  recipients.  Default: 0 
(off). 

■ uquotacheck:  provides  message  bouncing  during  SMTP  session  in  case  of 
mailbox  quota  overflow.  Default:  0 (off). 

■ localtime:  provides  generation  of  date  stamps  in  local  timezones  for  various 
qmail  programs.  Default:  0 (off). 

■ samsgsize:  maximum  message  size,  in  bytes  to  be  send  to  spamd. 

■ catchall:  provides  ability  to  disable  the  work  of  ‘Catch  All’  options  independently 
of  user  settings.  Default:  1 (enabled). 

■ re  j ectdiscardedmaii:  rejects  incoming  messages  to  mailboxes  with  discard 
option  at  SMTP  level.  Default:  0 (disabled). 

■ skipsachk,  skipcachk:  skip  Spamassassin  (SA)/Antivirus  (CA)  check: 

■ skipcachk=0  and/or  skipsachk=0  or  absent:  default  settings  - always  CA 
and/or  SA  check,  if  enabled 

■ skipcachk=1  and/or  skipsachk=1 : for  SMTP  authenticated  users  CA  and/or 
SA  heck  skipped 
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■ skipcachk=2  and/or  skipsachk=2:  for  SMTP  connections  with  dynamic  or 
static  open  relays  or  for  SMTP  authenticated  users  CA  and/or  SA  check  skipped 

Note:  As  an  example  of  patterns,  see  the  canonical  method  filter  for  spam  e-mail  in 
READMESPAMCONTROL 

(http://www.fehcom.de/qmail/spamcontrol/README  spamcontrol.html). 
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Mail  Client  Headers 

x-originating-ip  and  x-Enveiope-To  mail  client  headers  are  included  in 
Parallels  H-Sphere  by  default.  They  introduce  the  following  controls: 

■ xoriginatingip:  includes  X-Originating-IP  header  into  mail  client  according  to 
AOL  recommendations,  http://postmaster.aol.com/faq/forwardinq.html  (enabled  by 
default) 

■ xenveioptoheader:  includes  X-Envelope-To  header  which  is  required  by  some 
mail  clients  to  identify  real  envelope  sender  (disabled  by  default) 


Autoresponder  Settings 


Parallels  H-Sphere  provides  autoresponder  policy.  Enter  the  necessary  parameters 
and  click  Submit: 


■ patterns_poiicy  - autoresponder  is  working  only  if  Sender  Filter  is  configured 
in  user  CP.  The  default  value  is  0 (disabled). 

■ autorepiy_poiicy  - provides  autoreply  if  SENDER  originating  IP  corresponds  to 
a target  receipient  IP  or  Subnet  only 
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Bounce  Message  Customization 

Parallels  H-Sphere  enables  bounce  and  doublebounce  messaging  in  case  mail  failed 

to  be  delivered.  Enter  the  necessary  parameters  and  click  Submit: 

■ bouncingip:  parameter  removed  in  Parallels  H-Sphere  3. 0 RC  2,  added  a 
separate  Outgoing  IP  to  mail  server.  Once  you  add  it  via  Admin  CP,  it  will  disappear 
from  Qmail  parameters. 

■ bouncef  rom:  the  email  user  messages  are  bounced  from.  Default:  MAILER- 
DAEMON; 

■ bouncehost:  the  literal  name  or  bouncehost  IP.  If  a message  is  permanently 
undeliverable,  qmail-send  sends  a single-bounce  notice  back  to  the  message’s 
envelope  sender,  from:  bouncefrom@bouncehost.  Default:  mail  server  name. 

■ doubiebouncehost:  the  literal  name  doublebouncehost  or  IP.  If  a single-bounce 
notice  is  permanently  undeliverable,  qmail-send  sends  a double-bounce  notice  to 
doubiebounceto@doubiebouncehost.  Default:  mail  server  name. 

■ doubiebounceto:  the  user  email  to  receive  doublebounce  messages. 

■ bouncesubject:  enter  bounce  message  subject. 

■ bouncemessage:  enter  the  text  of  the  bounce  message. 

■ doubiebouncesub  j ect:  enter  doublebounce  message  subject. 

■ doubiebouncemessage:  enter  the  text  of  the  doublebounce  message. 

■ temperror:  considers  temporary  error  a permanent  one  for  local,  remote,  and 
local  & remote  mails. 

■ strictbounce:  strictbounce  allows  for  bounce  to  act  as  double  bounce  and  for 
bounce  and  double  bounce  to  act  as  triple  bounce  (when  bounce  message  is 
discarded). 

Mail  Protocols 

Choose  a system  SMTP  relay  for  your  mail  server  - POP  before  SMTP  and  SMTP 

AUTH. 

■ smtpauth:  enables  SMTP  AUTH  extension 

Default:  0 (AUTH  LOGIN/PLAIN/CRAM-MD5  SMTP  extension  is  disabled) 

■ popbef oresmtp:  enables  POP-BEFORE-SMTP 

■ opensmtptimeout:  allows  to  set  open  relay  lifetime,  in  minutes,  after  POP-before- 
SMTP  authentication.  Default:  180  min. 
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SPF  (Sender  Policy  Framework) 

Parallels  H-Sphere’s  SPF  (on  page  163)  implementation  at  the  SMTP  server  level  is 
based  on  this  qmail  patch:  http://www.saout.de/misc/spf/.  It  introduces  the  following 
qmail  controls: 

■ spfbehavior:  turns  SPF  checking  on/off.  The  default  value  is  0 (off).  You  can 
specify  a value  between  0 and  6: 

■ 0:  Never  do  SPF  lookups,  don’t  create  Received-SPF  headers 

■ 1 : Only  create  Received-SPF  headers,  never  block 

■ 2:  Use  temporary  errors  when  you  have  DNS  lookup  problems 

■ 3:  Reject  mails  when  SPF  resolves  to  fail  (deny) 

■ 4:  Reject  mails  when  SPF  resolves  to  softfail 
• 5:  Reject  mails  when  SPF  resolves  to  neutral 

■ 6:  Reject  mails  when  SPF  does  not  resolve  to  pass 
Values  bigger  than  3 are  strongly  discouraged. 

Important:  This  setting  can  be  overridden  using  the  environment  variable 
SPFBEHAVIOR , e.g.  from  tcpserver  rules. 

Note:  If  RELAYCLIENT\s  set,  SPF  checks  won’t  run  at  all.  (This  also  includes 
SMTP-AUTPI  and  similar  patches) 

■ spf  rules:  sets  a line  with  local  rules,  i.e.,  rules  that  are  executed  before  the  real 
SPF  rules  for  a domain  would  fail  {fail,  softfail,  neutral). 

They  are  also  executed  for  domains  that  don’t  publish  SPF  entries. 

■ spf  guess:  sets  a line  with  guess  rules,  i.e.,  rules  that  are  used  if  the  domain 
doesn’t  publish  SPF  rules.  The  local  spfrules  are  always  executed  afterwards. 

■ spf  exp:  customized  SPF  explanation.  The  explanation  is  the  line  returned  to  the 
SMTP  sender  when  a mail  is  rejected  at  the  SMTP  level.  You  can  use  macro 
expansion.  If  a domain  specifies  its  own  explanation  it  is  going  to  be  used  instead. 
The  SMTP  answer  when  rejecting  mails  will  look  like:  550  the  expanded  SPF 
explanation  (#5.7.1) 
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SRS  (Sender  Rewriting  Scheme) 

SRS  (on  page  163)  is  implemented  with  the  following  qmail  control  files  located  in  the 

/ var/ qmail/ control/ srs  directory: 

■ revers_srs_secrets:  contains  keys  called  secrets  to  form  hash  for  SRS 
address  for  reverse  mail.  The  file  contains  the  list  of  secrets,  each  in  separate  line. 
The  most  recent  key  is  on  top  of  the  list.  Qmail  takes  it  first  when  checking  SRS 
address,  and  if  it  doesn’t  fit,  Qmail  takes  these  keys  one  after  another.  If  none  fit, 
the  message  will  be  rejected.  The  file  has  400  permissions  and  vpopmaikvchkpw 
ownership. 

■ srs_secrets:  secrets  for  SRS  address  in  forwards.  The  file  has  400  permissions 
and  qmailkqmail  ownership. 

■ srs_secrets_age:  an  auxiliary  file  containing  information  when  each  key  in 
revers_srs_secrets  and  srs_secrets  was  created.  It  is  generated  by  the 

/var/ qmai l/bin/ sets rs secret  script  and  consists  of  the  lines  in  the  following 
format: 

key  timestamp 

■ srs_max_age:  an  integer  value  (in  seconds)  for  the  maximum  permitted  age  of  a 
rewritten  address.  SRS  rewritten  addresses  expire  after  a specified  number  of  days 
after  which  it  is  assumed  no  more  bounces  may  be  generated  in  response  to  the 
original  mail.  Mail  sent  to  expired  SRS  address  is  dropped  without  ceremony.  The 
default  (about  a month)  should  be  appropriate  for  all  purposes. 

These  controls  are  initiated  and  set  by  running  the  /var/qmaii/bin/setsrssecret 
script.  You  can  run  this  script  also  as  cron  (on  page  33)  on  mail  servers. 

Read  more  about  SRS  qmail  controls  at  http://www.libsrs2.org/docs/index.html. 

Command  Line  Qmail  Configuration 

Qmail  installation  directory  is  usually  /var/qmaii/. 

SMTPd  configuration  files  are  also  called  control  files.  Each  SMTP  parameter  is 
configured  in  its  own  control  file  with  the  same  name,  for  example, 

/var/qmail/control/smtpauth  for  smtpauth  parameter. 

All  controls  are  placed  in  one  configuration  file,  /var/qmaii/controi/options. 

To  view  SMTP  server  configuration,  run  the  qmaii-showcti  utility,  under  root: 

# /var/qmail/bin/qmail-showctl 

You  will  get  the  list  of  SMTP  parameters.  Each  line  in  the  list  has  the  following  format: 
smtp_parameter.  [(Default.)]  Value 

Each  stmp_parameter  may  be  set  in  its  own  control  file  with  the  same  name  located  in 
the  /var /qmail /control  directory..  The  file  contains  the  parameter’s  value.  If  the 
file  is  not  found,  the  default  value  is  taken  and  the  default  notification  (Default. ) 
shows  up  in  the  configuration  list. 


158  Mail  System 


Syslog  Facility/Level  Configuration  For  rblsmtpd 

rblsmtpd  is  a generic  tool  to  block  mail  from  RBL-listed  sites.  It  is  located  in 

/hsphere/ shared/bin/ rblsmtpd. 

It  is  possible  to  customize  syslog  facility/level  settings  for  rblsmtpd  to  redirect 
messages  to  custom  log  files.  The  following  facilities/levels  are  customizable  (read  man 
3 syslog  for  details): 


Facilities 

Levels 

LOG  AUTH 

LOG  AUTHPRIV 

LOG  CRON 

LOG  DAEMON 

LOG  FTP 

LOG  KERN 

LOG  LOCALO  . . . 

LOG  LOCAL 7 

LOG  LPR 

log_mail  (default) 

LOG  NEWS 

LOG_SYSLOG 

LOG  USER 

LOGJJUCP 

LOG  EMERG 

LOG  ALERT 

LOG  CRIT 

LOG  ERR 

LOG  WARNING 

log  notice  (default  for 

FreeBSD) 

log  info  (default  for  Linux) 

LOG  DEBUG 

Custom  facility/level  records  are  set  in  the  /var/qmaii/controi/rbisysiog  file, 
for  example: 

L0G_L0CAL7 : LOG_WARN  I NG 

Also  you  must  add  the  respective  record  in  /etc/sysiog . conf  (see  man 
syslog.  conf  for  details)  to  redirect  messages  to  a new  log  file,  for  example: 

local7.warn  /var/log/myrbllog 

File  /var/ qmaii/ con troi/sys facility  contains  name  of  syslog  facility  (one  from 
among  log_localo  . . . log_local7)  used  to  gather  mail  traffic  statistics  (on  page 
175). 

SMTP  Log 

Maillog  format  is  extended: 

■ remote  IPs  of  SMTP  sessions  are  logged  by  default; 

■ smtplog  parameter  is  introduced  in  the  /var/qmail/control/options  file: 

■ 0 default  logging  mode 

■ 1 : restricted  mode  of  SMTP  session  logging 

■ 2:  complete  SMTP  logging 

This  parameter  is  not  included  in  CP  and  is  not  modified  in  admin  interface,  as  it 
serves  for  debug  purpose  only. 
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Mail  Client  and  ESMTP  Destination  Server 

Mail  client  can  check  if  the  following  extensions  are  available  on  the  destination  server 
and,  if  so,  use  them. 

■ ESMTP  STARTTLS  extension  defined  in  RfC  RFC3207 

■ ESMTP  SIZE  extension  defined  in  RfC  1870 

■ ESMTP  PIPELINING  extension  defined  in  RfC  2920 

By  default,  only  esmtp  size/pipelining  check  is  provided  if  destination  server 
supports  them. 

Switching  over  qmaii-remote  client  to  use  them  is  made  via  mconnectext  control 
file  with  content  of  the  following  format: 


where  i equals  0 or  l and 

■ First  ‘i’  corresponds  to  STARTTLS 

■ Second  ‘i’  corresponds  to  SIZE 

■ Third  ‘i’  corresponds  to  PIPELINING 
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Qmail-spp  Support 

Parallels  H-Sphere  adds  a qmail-spp  engine  (http://gmail-spp.sourceforge.net/)  which 
provides  plugin  support  to  qmail's  SMTP  daemon  (qmail-smtpd).  It‘s  written  entirely  in 
C using  native  qmail  libraries,  so  it  does  not  create  any  dependencies.  Qmail-spp 
engine  implementation  is  aimed  to  add  rbispp  plugin  as  a replacement  for 

rblsmtpd. 

To  make  the  server  and  plugins  work  faster,  follow  the  rules: 

■ Use  the  engine  only  as  circumstances  may  require,  i.e.  to  add  new  plugins 

■ Do  not  run  plugins  via  system  shell,  that  means  without  adding  just  before  plugin 
path.  Avoid  command  line  parametres  or  plugins  written  on  shell/perl 

■ Use  full  pathes  to  plugins 

■ Accumulate  functionality  in  one  particular  plugin  rather  than  use  different  plugins 

Configuration  Details 

Qmail-spp  support  can  be  enabled  via  CP  interface  and  configured  in 

/var/ qmail/ control/options  file  (qmailspp  boolean  parameter).  When  qmail-spp 

engine  is  involved,  qmail-smtpd  tries  to  read  the  main  default  configuration  file  of  qmail- 

spp  /var/ qmail/ control/ smtppiugins  that  consists  of  few  sections  one  for  each 

command: 

connection  - for  plugins  run  just  after  client  connection 

helo  - for  HELO/EHLO 

mail  - for  MAIL 

rcpt  - for  RCPT 

data  - for  DATA 

auth  - for  AUTH 

Mind  that  you  have  to  specify  full  pathes  to  plugins  while  configuring  qmail-spp.  To  find 
more  info  on  syntax,  refer  to  qmail-spp  documentation  (http://gmail- 
soo.sourceforge.net/doc/). 

To  add  plugins  to  conf  file,  use  the  following  utility: 

/var/qmail/bin/spp-conf  -h 

Usage: 


■ a|-r|-R  -h  -b  -s  -p  plugin_name  -t  category_name 

plugins  must  be  located  at  /var/qmail/control/plugins  directory. 

plugin_name:  relative  plugin  name 

category_name:  connection,  auth,  helo,  mail,  rcpt,  data 

■ a : add  plugin  (by  default) 

■ r : remove  plugin 

■ R : remove  all  plugins 

■ b : input  from  stdin  set  of  rows,  format:  category_name;plugin_name 

■ s : plugin  is  executed  via  shell  -i  : check  and  fix  plugin  permissions 
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Qmail  TLS  Support 

In  mail  service  configured  with  SSL,  TLS  is  disabled  by  default  (maii-ssi-proto 
script  was  used  to  switch  it  on). 

To  enable  TLS  support  (with  possible  protocols:  SSLv2,  SSLv3,  TLSvl,  by  default 
SSLv3  only),  run: 

/hsphere/local/config/mail/scripts/mail-ssl-proto  -r  -t  SSLv3, TLSvl 

Where: 

■ maii-ssi-proto  script  sets  list  of  SSL  protocols  used  by  mail  service. 

■ -r  provides  mail  service  restart. 


Integrated  Plugins 

Rblspp  Plugin 

Rblspp  plugin  was  added  as  a replacement  for  rbismtpd.  It  resolves  the  RBL  check 
delay  problem  for  successful  SMTP  authenticated  connections.  For  this,  ucspi-tcp- 
0 . 88-rbispp.patch  patch  was  combined  with 

(http://xs3.b92.net/tomislavr/qmail.html#ii)  ifauthskip . c,  and  command  line 
parametres  were  removed  to  speed  up  the  plugin  launch. 

If  RBL  check  is  involved  but  plugin  support  is  disabled,  default  rbismtpd  scheme  is 
used. 
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Choosing  Remote  MySQL  Logical  Server 
for  SpamAssassin 

Parallels  H-Sphere  mail  logical  server  is  by  default  installed  on  a physical  box  together 
with  Web  and  MySQL  servers  on  the  same  box,  thus  SpamAssassin  uses  MySQL 
database  on  the  same  server. 

It  is  made  possible  to  choose  an  alternative  remote  MySQL  server  for  SpamAssassin 
database.  This  is  in  particular  important  for  the  implementation  of  load  balanced  mail 
cluster  (on  page  300)  where  it  is  required  that  SpamAssassin  is  configured  to  use 
remote  MySQL  servers. 

> To  choose  a remote  remote  MySQL  server  for  SpamAssassin: 

1.  Login  as  cpanel  user  (on  page  53)  and  set  the  following 
property  in 

~ cpanel / shiva /p sof t_con f ig/hsphere .properties : 
EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  41)  to  apply  changes. 

Important:  If  EXTERNAL  SERVICE  USAGE  is  not  set  or  is  not  TRUE,  you  won’t 
be  able  to  choose  an  external  MySQL  server  for  SpamAssassin! 

2.  In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  mail  logical  server,  and  select  a MySQL  server  from  the  Choose 
External  Spamassassin  DB  Server  dropdown  menu  in  Mail  Server  Additional 
Options . 

3.  Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 

hspackages  reconfig=spamassassin 

Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 

4.  To  move  SpamAssassin  DB  content  from  the  older  local  MySQL  DB, 
run  the  following  script  on  the  source  box: 

/hsphere/pkg/ scripts/uprocedures/dbs_content  -h 
Usage: 

dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 

dbtype:  horde  or  spamassassin  or  phpmyadmin 

ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the 
corresponding  mail  logical  server. 

password:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding 
mail  logical  server. 
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SPF  and  SRS 


Sender  Policy  Framework  (SPF)  (http://spf.pobox.com/)  is  a mechanism  for 
preventing  sender  forgery  in  SMTP  transaction,  thus  allowing  domain  owners  control 
over  who  may  send  mail  from  their  domain. 

Sender  Rewriting  Scheme  (SRS)  (http://spf.pobox.com/srs.html)  is  a mechanism  for 
rewriting  sender  addresses  when  a mail  is  forwarded  in  such  a way  that  mail 
forwarding  continues  to  work  in  an  SPF  compliant  world. 

SRS  can  work  without  SPF,  but  not  vice  versa,  i.e.,  issues  with  forwards  may  arise  if 
SPF  is  implemented  without  SRS. 

WARNING:  If  SRS  is  enabled  in  Parallels  H-Sphere,  the  problems  may  arise  with 
forwarding  mail  to  servers  where  SRS  is  not  supported.  In  such  cases,  mail  may  return 
undelivered  back  to  users.  The  next  Parallels  H-Sphere  mail  service  package  will 
provide  a more  friendly  way  to  handle  forwards  to  such  servers. 

This  documentation  explains  the  arrangement  of  these  resources  at  the  server  level. 
Please  read  how  to  enable  and  configure  SPF  and  SRS  in  admin  CP  in  Parallels  H- 
Sphere  Service  Administrator  Guide. 

In  this  section: 


SPF  (Sender  Policy  Framework) 164 

SRS  (Sender  Re-write  Scheme) 166 
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SPF  (Sender  Policy  Framework) 

SPF  is  implemented  at  the  level  of: 

- DNS  TXT  records 

■ SMTP  server. 

DNS  TXT  Records 

Once  the  SPF  resource  is  enabled  in  Parallels  Fl-Sphere,  DNS  TXT  records  will  be 
provided  for  each  A and  MX  records  in  E.Manager->DNS  Manager. 

DNS  TXT  records  have  the  following  format: 

domain.com  IN  TXT  “v=spf1  spf_string” 

Flere,  spf  l is  SPF  version,  and  spf_string  takes  the  combination  of  the  so-called 
mechanisms:  "a,  ptr,  mx,  ip4,  include,  all",  all  is  a finalizing 
mechanism  and  must  be  placed  at  the  end. 

Please  read  more  explanations  on  mechanisms  in  TXT  DNS  records 
(http://spf.pobox.com/mechanisms.html). 

Each  mechanism  may  have  a prefix  pointing  to  a certain  type  of  processing  messages: 

■ - fail  (message  is  rejected) 

■ ~ softfail  (message  is  passed  with  warning) 

■ + pass  (message  is  passed  - the  default  prefix  value) 

? neutral  Thus,  the  simplest  SPF  record  will  be: 
domain.com  IN  TXT  “v=spf1  -all” 

It  means  that  you  deny  sending  any  mail  from  this  domain,  i.e.,  you  may  use  this 
domain  for  any  hosting  except  mail  hosting,  (-all  is  thus  somewhat  similar  to  deny  all  in 
Apache). 

Example: 

Consider  the  following  record: 

domain.com  IN  TXT  “v=spf1  mx  a:test. com/24  ptr:test2.com  -all” 

If  a message  is  sent  with  MAIL  FROM:  test@test3 . com  and  from  the  client  IP 
4. 5. 6. 7,  SMTP  server  will  check: 

a whether  test3.com  MX  records  (at  least  one  of  them)  are  resolved  to  IP  4.5. 6. 7; 
b whether  the  IP  4.5. 6. 7 is  in  a test.com’s  IP  subnet  (mask  255.255.255.0); 
c whether  the  PTR  record  for  IP  4. 5. 6. 7 is  resolved  to  test2.com; 

If  none  of  the  above  conditions  are  met,  then  the  last  directive  -all  meaning  “deny 
all  other”  takes  effect,  and  the  message  will  be  rejected. 

The  include  directive  is  used  if  you  wish  to  delegate  SPF  check  for  another  domain, 
for  example: 

“v=spf1  include:example.net  -all” 

SMTP  Server 
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At  the  level  of  qmail  server,  the  following  SMTP  parameters  should  be  configured  in 
respective  files  in  /var/qmaii/controi  directory: 

■ spfbehavior 

■ spfrules 

■ spfguess 

■ spfexp 

For  more  details,  refer  to  Qmail  Configuration  (on  page  142)  and  SPF  Implementation 
for  Qmail  (http://www.saout.de/misc/spf/). 
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SRS  (Sender  Re-write  Scheme) 

SRS  mechanism  is  used  in  two  cases: 

■ To  form  SRS-compliant  mail  address  for  forwarding  messages  via  forward  mail 
resources,  in  accordance  with  SRS  convention; 

■ To  form  reverse  SRS-compliant  reverse  mail  address  in  case  of  reply. 

Parallels  H-Sphere  provides  the  following  Qmail  controls  for  SRS  (they  are  located  in 

the  /var/qmail/control/srs/  directory): 

■ SRS  secrets  files:  reverse_srs_secrets  (for  reverse  mail)  and  srs_secrets 
(for  forwards).  These  files  contain  a set  of  lines  with  keys,  each  key  in  a separate 
line.  These  keys,  called  secrets,  are  used  to  validate  hash  from  SRS  formatted  e- 
mail  address.  The  most  recent  key  is  on  top  of  the  list.  Qmail  takes  it  first  when 
checking  SRS  address,  and  if  it  doesn’t  fit,  Qmail  takes  these  keys  one  after 
another.  If  none  fit,  the  message  will  be  rejected. 

The  revers  srs  secrets  file  has  400  permissions  and  vpopmaikvchkpw 
ownership. 

The  srs  secrets  file  has  400  permissions  and  qmailhqmail  ownership. 

■ srs_maxage  - an  integer  value  for  the  maximum  permitted  age  of  a rewritten 
address.  SRS  rewritten  addresses  expire  after  a specified  number  of  days  after 
which  it  is  assumed  no  more  bounces  may  be  generated  in  response  to  the  original 
mail.  Mail  sent  to  expired  SRS  address  is  dropped  without  ceremony.  The  default 
(about  a month)  should  be  appropriate  for  all  purposes. 

For  details,  please  refer  to  http://www.libsrs2.org/docs/index.html. 

The  script  /var/qmaii/bin/setsrssecret  runs  as  cron  (on  page  33)  on  mail 

servers  to  set  these  controls. 


Updating  SpamAssassin  Rulesets 
Automatically 

Below  are  two  scripts  used  for  automatical  update  of  SpamAssassin  rulesets. 

In  this  section: 


Sa-update  Script 

Rules  Du  Jour  Script 
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Sa-update  Script 

Sa-update  (http://saupdates.openprotect.com/)  is  a script  aimed  at  the  dynamic  update 
of  basic  spam  assassin  rules  to  catch  different  kind  of  spam.  It  provides  a possibility  to 
add  other  channels,  but  at  your  own  risk. 

By  default  sa-update  script  is  located  at: 

■ /hsphere/local/conf ig/mail/spamassassin/sa-update-keys - pgp 

key-rings.  It  is  automatically  formed  in  the  post  install  section  for  default  chanel. 

■ /hsphere/ local/  conf  ig/mail/  spamassas  sin  /sa-update  - directory 
where  updated  rules  are  located. 

The  /hsphere /local/  conf  ig/mail/  spamassas  sin/  scripts/  saupdate  script 
that  updates/checks  for  new  rules  can  be  customized  according  to  your  own  needs  by 
adding  new  rules.  This  script  remains  untouched  after  further  hsphere-mail-service 
updates. 


Rules  Du  Jour  Script 

RulesDuJour  (http://www.exitQ.us/index.php?paqename=RulesDuJour)  is  a bash  script 
aimed  at  automatical  download  of  new  versions  of  SpamAssassin  rulesets  as  the 
authors  release  new  versions.  As  FreeBSD  does  not  include  bash  by  default,  Parallels 
H-Sphere  mail  service  package  containing  RulesDuJour  also  includes  the  bash 
installation  for  FreeBSD.  This  script  must  run  daily  as  a cron  task  to  keep  additional 
custom  SpamAssassin  rules  up  to  date. 

At  the  mail  server  level,  RulesDuJour  is  implemented  by  the  following  scripts: 

■ Initialization  script: 

/hsphere/local/conf ig/mail/spamassassin/scripts/init  rules  du 
_j  our 

■ Deletion  script: 

/hsphere /local/ conf ig/mail/ spamassas sin/ scripts/ delete  rules 
du_j  our 

■ RulesDuJour  SA  ruleset  update  script: 

/hsphere/local/conf ig/mail/spamassassin/scripts/rules  du  jour 


In  this  section: 


Initialization  Script 168 

Configuration  File 169 
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Initialization  Script 

Initialization  script  is  launched  upon  enabling  the  Automatic  Ruleset  Update  (Rules  Du 
Jour)  option  in  SpamAssassin  Manager  via  the  administrator  control  panel: 

1 . It  creates  the  default  RulesDuJour  config  file 

/hsphere/local/conf  ig/mail/spamassassin/rulesdu  j our  . The  init 
script  syntax  (run  it  with  the  -h  option  to  get  help): 

# 

/hsphere/local/ conf ig/mail/ spamassassin/ scripts/ini t_rules_du 
_jour  -h 

Usage: 

init  rules  du  jour  [ -r  rulesets  ] [ -e  email  ] 

rulesets:  list  of  comma  separated  ruleset;  possible  values: 

TRIPWIRE  EVILNUMBERS  SARE_RANDOM  (default:  all) 

email:  address  where  e-mail  notifications  on  SA  rulesets 

update  go  (default:  none) 

The  script  is  used  to  set  values  for  SA  rulesets  to  be  updated  and  the  e-mail 
address  where  update  notifications  will  be  sent.  See  Configuration  File  for  details. 

2.  It  adds  the  RulesDuJour  SA  ruleset  update  script 

/hsphere/local/ conf ig/mail/ spamassassin/ scripts/ rules_du_j  our 

to  mail  server  cron  jobs  (on  page  33)  starting  daily  at  1 :00  AM: 

0 l * * * 

/hsphere/local/ conf ig/mail/ spamassassin/ scripts/rules_du_jour 
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Configuration  File 

Initialization  forms  the  RulesDuJour  config  file 

/hsphere/ local/ conf  ig/mail/ spamassassin/ rulesdu j our.  It  has  the 

following  format: 

# cat  rulesdujour.default 

TRUSTED_RULESETS=”TRIPWIRE  EVILNUMBERS  SARE_RANDOM” 

SA_DIR=/hsphere/local/config/mail/spamassassin 

EMAIL_RDJ_UPDATE_ONLY= 

SINGLE_EMAIL_ONLY=true 

MAIL_ADDRESS= 

SA_LINT=”/hsphere/shared/bin/spamassassin — lint” 
SA_RESTART=7etc/rc.d/init.d/spamd  restart” 

TMPDIR=”${SA_DIR}/RulesDuJour” 

This  sample  config  file  is  for  Linux  servers.  For  FreeBSD,  it  has  a different  spamd 
restart  format: 

SA_RESTART=,7usr/local/etc/rc.d/spamd.sh  restart” 

Two  config  files  variables  - trusted_rulesets  and  mail_address  - can  be  set  by 
the  init  script  and  via  Control  Panel  at  the  SpamAssassin  Manager  page: 

■ TRUSTED_RULESETS  - choose  under  what  categories  custom  rulesets  need  to 
be  included  and  updated: 

■ BLACKLIST  a blacklist  of  spammers. 

■ BLACKLIST_URI  looks  for  these  domains  inside  URL’s  in  the  message. 

■ BOGUSVIRUS  lists  bogus  virus  warnings  and  similar. 

■ RANDOMVAL  list  of  tags  spammers  sometimes  forget  to  convert  in  spam. 

■ SARE_ADULT  designed  to  catch  spam  with  “Adult”  material. 

■ SARE_BAYES_POISON_NXM  using  lists  of  words  with  equal  length. 

■ SARE_BML  designed  to  catch  “business,  marketing  and  educational”  spam. 

■ SARE_BML_PRE25X  designed  to  catch  “business,  marketing  and  educational” 
spam. 

■ SARE_FRAUD  designed  to  catch  “Nigerian  419”,  “International  Lotto”,  etc.  type 
scams. 

■ SARE_FRAUD_PRE25X  designed  to  catch  “Nigerian  419”,  “International  Lotto”, 
etc.  type  scams. 

■ SARE_HEADER  contain  Pleader  rules  that  are  not  found  in  other  SARE 
rulesets. 

■ SARE_OEM  tries  to  detect  people  selling  OEM  software  to  consumers. 

■ SARE_RANDOM  tries  to  detect  common  mis-fires  on  bulk  mail  software.  Many 
signs  are  found  like:  %RND_NUMBER,  etc. 

■ SARE_SPECIFIC  ruleset  which  flags  specific  spam  and/or  spam  from  specific 
spammers. 

■ SARE_SPOOF  tries  to  detect  common  spoofing  attempts  by  spammers.  Many 
use  a Message-ID  of  one  provider  but  the  message  was  never  passed  through 
the  suggested  system. 

■ TRIPWIRE  searches  for  3 characters  that  shouldn’t  be  together.  This  is  based 
on  the  English  language. 

■ RANDOMVAL  lists  tags  spammers  sometimes  forget  to  convert  in  spam. 
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■ SARE_EVILNUMBERS  lists  addresses  and  phone  numbers  harvested  from 
spam. 

■ SARE_GENLSUBJ  contains  Subject  header  rules  that  are  not  found  in  other 
SARE  rulesets. 

■ SARE_HIGHRISK  is  developed  because  there  are  spam  signs  which  readily 
detect  spam,  and  which  in  our  testing  do  not  flag  significant  ham,  but 
theoretically  there  is  no  reason  for  such  rules  not  to  flag  ham.  We  therefore 
consider  these  to  be  “high  risk”  rules,  useful  for  many  systems  at  this  time,  but 
not  suitable  for  systems  that  must  be  very  conservative  and  cautious  in  their 
spam  detection. 

■ SARE_HTML  contains  HTML  coding  rules  that  detect  various  spammer  tricks 
applied  through  HTML  coding  within  messages. 

■ SARE_OBFU  looks  for  obfuscation  within  emails.  It  looks  for  the  various  tricks 
spammers  use  to  hide  their  message  from  spam  filters,  while  keeping  their 
messages  readable  to  humans.  It  treats  these  as  spamsign. 

■ SARE_REDIRECT  detects  commonly  abused  redirectors  and  uri  obfuscation 
techniques. 

■ SARE_SPAMCOP_TOP200  contains  top  200  spam  relays  condensed  into  as 
few  rules  as  possible. 

■ SARE_STOCKS  contains  set  of  rules  for  stock  spams. 

■ SARE_UNSUB  looks  for  common  unsubscribe  phrases  and  codes  in  spam. 

■ SARE_URI  contains  files  look  for  spamsign  in  URI  links  within  emails.  It  is  not 
intended  to  replace  SURBL  or  BigEvil,  but  instead  will  use  characteritics  that 
these  domain-based  tests  cannot  track. 

■ SARE_WHITELIST  used  to  whitelist  newsletters  and  mailing  lists  that  are 
controlled/monitored  to  be  free  of  spam,  but  might  occasioanlly  be  flagged  as 
spam  by  SpamAssassin  because  of  “spammy”  contents. 

■ ZMI_GERMAN  contains  German  ruleset. 

■ MAIL_ADDRESS  - the  e-mail  address  where  SA  ruleset  update  notifications  will  be 

sent.  If  the  field  is  empty,  no  notifications  will  be  sent. 
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Migrating  Mail  Server/IP 

> To  move  the  mail  server  to  another  machine: 

1.  Prepare  Servers 

1 . Prepare  a new  box  with  a mail  server. 

2.  Create  a new  physical  server  and  add  a mail  server  group  (or  add  this  group  to 
the  physical  server  you  are  planning  to  move  mail  server  to). 

3.  Disable  signup  for  the  mail  server. 

2.  Move  Mail  Content 

1 . As  the  cpanel  user  (on  page  53),  ssh  to  your  target  mail  server: 
ssh  rootQ<TARGET_MAIL_SERVER_IP> 

2.  Move  the  following  directories  from  the  source  to  the  target  mail  server: 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/domains 
/ /hsphere/ local/var/ vpopmail/domains / 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVERJP> : /hsphere/local/var/vpopmail/etc/ 

/hsphere/local/var/vpopmail/etc/ 

rsync  -arzgop  -e  ssh 

roo tQ<SOURCE_MAIL_SERVER_IP> : /var/qmail/control/ 

/ var/ qmail/ control/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /var/qmail/users/  /var/qmail/users/ 
rsync  -arzgop  -e  ssh  rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/horde/ 
~mysql/ horde/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/ spamassassin/ 

~mysql/ spamassassin/ 

3.  Update  System  Database 

1 . Stop  the  Control  Panel  (on  page  41). 

2.  Log  into  the  Parallels  H-Sphere  system  database  (on  page  53)  and  run  the 
following  queries: 

update  l_server  set  p_server_id=<TARGET_PHYSICAL_SERVER_ID>  where 
id =<MAIL_LOGICAL_SERVER_ID> ; 

(1  record) 

update  l_server_ips  set  ip= ' <TARGET_MAI L_SERVER_I P> ' , 
mask='  <TARGET_MAIL_SERVER_MASK> ' where 
l_ser'ver _id=<MAIL_LOGtCAL_SERVERJD>  and  flag=4; 

(1  record) 

3.  Start  the  Control  Panel  (on  page  41). 

4.  Update  Reseller’s  Server  Aliases 

As  the  cpanel  user,  run  the  following  java  tool: 

java  psof t . hsphere . tools . ServerAliasesRenamer— lserver 
<MAIL_LOGICAL_SERVER_ID> 

5.  Mail  Content  Final  move 
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1 . Stop  the  mail  and  mysql  service  (on  page  39)  on  the  source  server 

2.  As  the  cpanel  user  (on  page  53),  ssh  to  your  target  mail  server: 
ssh  roo t@ < TARGET _MA!L_SERVERJP> 

3.  Repeat  rsync  commands  from  Step  2 from  the  target  server 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVERJP> : /hsphere/local/var/vpopmail/ domains 
/ /hsphere/ local/var/ vpopmail /domains / 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/ etc/ 

/hsphere/local/var/vpopmail/etc/ 

rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /var/qmail/control/ 

/ var/ qmail/ control/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /var/ qmail/users/  /var/qmail/users/ 
rsync  -arzgop  -e  ssh  rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/horde/ 
~mysql/ horde/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/ spamassassin/ 

~mysql/ spamassassin/ 

4.  Start  the  mysql  service  (on  page  39)  if  you  have  a mysql  service  on  the  source 
box. 

6.  Enable  Qmail  Forwarding  For  The  Time  of  DNS  Propagation 

The  possibility  to  use  POP3-before-SMTP  and  SMTP  AUTH  Authentication  for  the 
time  of  migration  has  been  implemented  since  mail2-all4  (/misc/mail2_all4.html).  If 
your  Parallels  H-Sphere  uses  an  older  mail  package,  please  skip  this  step. 

1 . Start  source  mail  server  with  the  “forward”  parameter: 

/etc/init .d/qmaild  forward 

When  prompted  “Enter  IP  address  of  the  destination  mail  server:  enter  the  IP  of 
the  target  physical  server.  This  IP  will  be  added  to  files 

/var/qmail/control/destip  and  /var/qmail/control/smtproutes 

and  will  be  used  for  further  server  restarts. 

2.  On  the  target  mail  server,  add  the  IP  of  the  source  server  as  an  IP  with  open 
relay. 

NOTE:  qmail  forward  switches  the  source  SMTP  server  into  relay  mode  and 
forwards  POP3  traffic  to  the  target  server  with  simultaneous  POP3-before- 
SMTP  authentication  on  the  source  box.  This  is  done  to  keep  using  the  old 
box  until  the  target  server's  DNS  settings  are  propagated  across  the 
Internet.  It  usually  takes  up  to  2 or  3 days.  After  that,  you  can  stop  the 
source  server. 

7.  Change  the  A DNS  record  for  main  zone. 

Go  to  the  E-Manager  ->  DNS  Manager  and  delete  the  A DNS  record  with  the  old  IP  and 
add  it  with  the  new  IP. 

8.  Finish  off  the  migration 

1 . Check  if  you  have  -qmaiid/controi/outgoingip  file.  If  yes,  change  the  IP 
in  this  file  to  the  new  one. 

2.  Restart  qmail  service  (on  page  39)  on  the  target  box. 
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3.  On  CP  server,  check  the 

~cpanel/ shiva/psoft  conf  ig/hsphere  .properties  file.  Here,  find  the 
SMTP_HOST  parameter.  If  it  is  set  to  the  old  mail  server  IP,  reset  it  to  the  new 
IP  or  to  the  SMTP  server’s  hostname. 

4.  If  SMTP_HOST  parameter  was  changed,  restart  the  Control  Panel  (on  page 
41). 

9.  Check  mail  server  functionality. 
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Moving  Mail  Domains 

Moving  mail  domains  in  Parallels  H-Sphere  is  not  fully  automated,  which  means  it  can 
be  applied  to  individual  domains  or  small  groups  of  domains.  The  below  procedure 
doesn’t  work  well  with  large  groups  of  mail  domains  or  entire  resellers. 

Please  be  prepared  that  due  to  the  propagation  of  the  new  IP  address,  mail  domain 
move  can  result  in  up  to  24  hour  downtime  and  inability  to  edit  the  mail  boxes. 

> To  move  a group  of  user  domains  from  one  mail  server  to  another: 

1.  On  the  new  mail  server,  log  in  as  root  and  run  the  following  commands 
for  each  domian: 

1.  Register  a new  mail  domain: 

~vpopmail/bin/vadddomain  <DOMAIN_NAME>  <ANYPASS> 

2.  If  the  domain  you  are  moving  has  domain  aliases,  set  up  each  alias  by  the 
following  command: 

~vpopmail/bin/vaddaliasdomain  <DOMAIN_NAME>  <ALIAS_NAME> 

3.  Get  the  location  of  this  domain  directory: 

~vpopmail/bin/vdominfo  <DOMAIN_NAME> 

4.  Remove  the  content  of  this  directory: 
rm  -rf  <DOMAIN_DIRECTORY> 

5.  Copy  the  content  of  the  original  maildomain  directory  from  the  source  server: 
scp  -r  root$<OLD_SERVER_IP> : <SOURCE_DOMAIN_DIRECTORY> 
<DOMAIN_DIRECTORY> 

6.  Update  ownership  of  the  domain  directory  and  its  content: 
chown  -R  vpopmail : vchkpw  <DOMAIN_DIRECTORY> 
where: 

<DOMAIN_NAME>  is  the  mail  domain 

<ANYPASS>  is  any  string.  Later  it  will  be  replaced  with  the  real  password 
<DOMAIN_DIRECTORY>  is  the  location  of  the  domain  directory  on  the  target  server 
<SOURCE_DOMAIN_DIRECTORY>  is  the  location  of  the  domain  directory  on  the  source 
server 

<OLD_SERVER_IP>  is  the  IP  address  of  the  source  mail  server. 

7.  Restart  mail  server  (on  page  44)  to  apply  changes. 

2.  If  the  domain  directory  path  is  different  on  the  source  and  target 
servers: 

1 . Go  to  the  domain  directory  on  the  target  server  and  update  all  mailbox  paths  in 
the  vpasswd  file  and  all  files  that  have  names  beginning  with  . qmaii- . 

2.  Add  and  delete  a temporary  mailbox  to  apply  changes: 

[root@mail3  example . com] # ~vpopmail/bin/vadduser 
blala@example . com 

Please  enter  password  for  blala@example.com: 
enter  password  again: 

[root@mail3  example . com] # ~vpopmail/bin/vdeluser 
blala@example . com 
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3.  On  the  old  mail  server,  log  in  as  root  and  delete  the  domains  using  this 
command  for  each  domain: 

~vpopmail/bin/vdeldomain  <DOMAIN_NAME> 

4.  Important!  Back  up  the  Parallels  H-Sphere  system  database. 

5.  Log  into  the  system  database  (on  page  53)  and  run  the  following 
queries: 

1 . Set  new  logical  server  id  for  each  domain  name: 

UPDATE  mail_services  SET  mail_server=<NEW_LSERVER_ID>  WHERE 
id= (SELECT  child_id  FROM  parent_child  WHERE  child_type=1000 
AND  parent_id= (SELECT  id  FROM  domains  WHERE 
name= ' <DOMAIN_NAME> ' ) ) ; 

2.  Get  current  values  from  the  MX  and  CNAME  records  for  the  moved  domains: 
SELECT  r . id , r . name , r . type , r . data , r . ttl , r . pref  FROM 
domains  d,  parent_child  pi,  parent_child  p2 , dns_records  r 
WHERE  d . name= ' <DOMAIN_NAME> ' AND  d.id  = pl.parent_id  AND 

pi . child_type=1000  AND  pl.child_id  = p2.parent_id  AND 
p2 . child_id  = r . id  AND  (p2 . child_type=1007  OR 
p2 . child_type=3006) ; 

3.  Update  MX  and  CNAME  records  with  the  new  values: 

UPDATE  dns_records  SET  data=' < TARGE T_MA I L_S E RVE R_NAME > ' WHERE 
id  in  (<MX_ID>,  <CNAME_ID>) ; 

where  <MX_ID>  and  <CNAME_ID>  are  the  record  IDs  you  got  on  the  previous  step. 

4.  Restart  Parallels  H-Sphere  (on  page  41)  to  apply  changes. 

6.  As  the  cpanel  user  (on  page  53),  update  your  DNS  settings  using  the 
DNS  Creator  utility: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz  -z  <DOMAIN_NAME> 
where  <DOMAIN_NAME>  is  the  domain  name  you  are  updating  MX  and  CNAME  for. 


Calculating  Mail  Traffic 

This  document  explains  how  Parallels  H-Sphere  collects  and  rotates  mail  traffic. 

Parallels  H-Sphere  cron  script  (on  page  33)  responsible  for  analyzing  mail  traffic  is 

/hsphere/ shared/ scripts/ cron/mail  anlz  . sh.  The  script  runs  daily, 
processes  the  qmail  traffic  log  file  (on  page  33)  and  collects  mail  statistics  into  the 
specially  formatted  dd.mm.YYYY.qmi.txt  log  files  in  the  Parallels  H-Sphere  statistics 
directory  /hsphere/ local /var/ statistic.  Here,  dd .mm.  yyyy  is  current  date 
timestamp. 

dd . mm . yyyy  . qmi . txt  log  files  contain  lines  of  the  following  format: 

|name|xFer(kB)|Hits_AII|Hits_HTML| 

where  name  is  the  domain  name,  xFer  is  the  total  traffic  in  kilobytes. 

Then,  Parallels  H-Sphere  TrafficLoader  utility  is  launched  by  cron  to  collect  mail  traffic 
from  the  statistics  directory  and  to  store  it  into  the  system  database.  TrafficLoader  also 
calls  the  /hsphere/ shared/ scripts/xf er_cat . pi  script  to  move  the  already 
loaded  mail  statistics  files  to  the  /hsphere /local /var/ statistic/ loaded 

directory  as  dd . mm . yyyy  . qmi . txt . gz  archives. 
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Mail  Traffic  Log 

qmail  writes  a detailed  mail  traffic  log  to  the  /var/hsphere/maii/iogs/stats  file. 
To  view  detailed  descriptive  mail  statistics  from  this  file,  run: 

/var/qmail/bin/mailstatistics  -v  -f  /var/hsphere/mail/logs/stats 

The  -v  option  provides  a verbose  mode. 

Log  records  in  the  file  have  the  following  format: 

date  host  msg_type[pid]:  timestamp|sender|recipient|bytes|status|attempts 
Here: 

■ date : date  where  the  message  is  sent  or  received,  e.g.,  “Jun  20  18:20:14” 

■ host:  mail  server  host,  e.g.,  “mail.example.com” 

■ msg_type:  in  for  incoming  thread,  and  out  for  outgoing  thread 

■ pid : PID  of  the  process 

■ timestamp:  UNIX  timestamp  (in  seconds  since  1 Jan  1970)  of  the  date  when  the 
message  is  sent,  e.g.,  1 1 1 9280814 

■ sender:  message  sender’s  e-mail  address 

■ recipient:  message  recipient’s  e-mail  address.  For  multiple  recipients  each  one  a 
separate  line  in  the  log 

■ bytes:  message  size 

■ status:  message  status.  It  is  different  for  incoming  and  outgoing  mail 
Incoming  mail: 

■ success  - message  is  received  successfully 

■ timeout  - no  response  from  the  source  host  while  receiving  the  message 

■ rejclam  - message  is  received  completely  but  detected  as  infected  when  the 
proper  mail  resource  is  configured  to  remove  virused  message 

■ rejspam  - message  is  received  completely  but  detected  as  spam  when:  (1)  the 
proper  mail  resource  is  configured  to  remove  spam  message  or  (2)  when  the 
score  of  the  spam  message  exceeds  the  MaxScore  parameter 

■ manyhops  - message  is  looping 

■ mboxoverquota  - over  quota 

■ badmime  - used  bad  mime  type  of  the  mail  message 
bytestooverflow - message  exceeds  size  limit  Outgoing  mail: 

■ success  - message  is  sent  successfully 

■ timeout  - no  response  from  destination  host  while  sending  the  message 

■ partial  - malformed  incoming  message 

■ readerr-  internal  server  problems 

attempts:  number  of  data  transfers  per  one  SMTP  session  Example: 
tail  -f  /var/hsphere/mail/logs/stats 

Jun  20  18:20:14  mail.example.com  in[1 6723]: 

1 1 1928081 4|test@yahoo.  com  |postmaster@test.com|69|success 
Jun  20  18:20:14  mail.example.com  in[1 6723]: 

1 1 1928081 4|test@yahoo.com|test@test.com|69|success 
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POP3  and  IMAP  Traffic 

To  view  detailed  descriptive  IMAP  statistics,  run: 

cat  /var/hsphere/mail/logs/stats | grep  -i  imap 

POP3  statistics: 

cat  /var/hsphere/mail/logs/stats | grep  -i  pop3 

POP3  and  IMAP  traffic  have  the  same  format  as  Qmail  traffic  (on  page  101),  except  the 
e-mail  addresses  there  look  like  imap@<accoi/nf>  for  POP3  and  pop3@<accounf>  for 
POP3. 


Web  Mailing  List  Traffic 

To  view  detailed  descriptive  web  mailing  list  statistics,  run: 
cat  /var/hsphere/mail/logs/stats  | grep  maillist 

Web  mailing  list  traffic  has  the  same  format  as  Qmail  traffic,  except  that  in  sender  field 
it  includes  ‘web@maiiiist’  to  identify  its  type. 


SpamGuard  Setup 

> To  set  up  SpamGuard: 

1.  Download  SpamGuard:  http://www.enderunix.org/spamquard/ 

2.  Execute  tar  xfz  spamguard-x  . x . tar  . gz 

3.  Go  to  / root/inst/ spamguard-x . x/ 

4.  Read  the  INSTALL  and  README  files 

5.  Install  SpamGuard  following  the  instructions  in  the  INSTALL  and 
README  files 

IMPORTANT:  You  must  put  all  your  system  domain  names  to  the  Spamguard’s  ignore 
list  to  avoid  any  casual  chance  of  their  appearance  in  the  blacklist! 

Please  follow  instructions  in  the  POST-INSTALL  file. 

Warning:  For  the  time  being,  there  is  no  effective  way  of  combining  mailing  lists  and 
spamguard  protection.  You  need  to  configure  spamguard  manually  by  setting  the 
maximum  allowed  number  of  recipients. 
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Parallels  H-Sphere  DNS  service  can  use  either  MyDNS  (on  page  186)  or  the  bind8.x, 
9.x  package.  If  you  use  the  Linux  RedHat  autoupdates,  be  careful  not  to  update  bind. 

To  disallow  user  zones  on  a particular  DNS  server,  disable  user  signup  for  this  logical 
server  through  Parallels  H-Sphere  web  interface.  This  way,  old  customers  will  keep 
using  it,  and  new  customers  won’t. 

Resellers  can  run  on  dedicated  and  shared  IPs.  You  can  disable  dedicated  IP  hosting 
for  resellers.  Read  how  to  configure  DNS  for  resellers  in  Parallels  H-Sphere  Service 
Administrator  Guide. 

Parallels  H-Sphere  does  not  provide  support  for  Reverse  DNS. 
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DNS  Config  Files 

The  main  configuration  file  location  is  /etc/named . conf 

It  contains  the  following  data: 
options  { 

directory  “/hsphere/local/var/named”; 
listen-on  { 127.0.0.1 ; 

YOURJPJ; 

YOUR_IP_2; 


YOUR_IP_N; }; 

notify-source  ; 

pid-file  “/hsphere/local/var/named/named.pid”; 

} ; 

zone  IN  { type  hint;  tile  “local/named. ca”; }; 

zone  “localhost”  IN  { type  master;  file  “local/localhost.zone”;  allow-update 
{ none; }; }; 

zone  “0.0.127.in-addr.arpa”  IN  { type  master;  file  “local/named. local”; 
allow-update  { none; }; }; 

include  “zonesjndex.conf”; 
acl  anyip{any;}; 

Parallels  H-Sphere  DNS  Zones 

The  main  named  directory  both  on  master  and  slave  DNS  servers  is 

/hsphere/local/var/ named/. 

It  Contains  the  zones  index  . conf  file,  the  zones  (NUMBER)  . conf  files  and  the 
zones  (NUMBER)  directories,  where  (NUMBER)  =1,2,...,  22 
This  structure  contains  Parallels  H-Sphere  DNS  info  and  files.  To  find  a zone,  execute 
the  following  commands: 

# cd  /hsphere/local/var/named/ 

# grep  “Zone.Name.com”  *.conf 

It  will  return  the  data  which  contains  the  zone  file  location.  But  please  do  not  modify  it 
manually,  especially,  if  you  do  not  understand  what  you  do. 
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The  locaihost  and  0.0.127.  in-addr . arpa  zones  files  are  located  in  the 

/hsphere/local/var/ named/ local/  directory. 

Custom  DNS  Zones 

If  you  need  to  add  a custom  zone,  we  recommend  placing  it  into  this  directory.  Note 
that  Parallels  H-Sphere  won’t  manage  your  custom  zones,  you  will  have  to  manage 
them  manually. 

Reverse  DNS 

Parallels  H-Sphere  does  not  manage  reverse  DNS.  To  configure  reverse  DNS  globally 
for  the  main  Parallels  H-Sphere  domain,  Parallels  H-Sphere  owner’s  ISP  or  domain 
registration  company  should  accordingly  configure  reverse  DNS  for  this  domain  on 
their  DNS  servers. 
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Restarting  Named 

> To  start,  stop,  or  restart  named  on  the  Parallels  H-Sphere  DNS  server: 

1.  Log  in  as  root. 

2.  Run  the  respective  command  below. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss!!! 
Linux: 

Starting:  / etc/ rc . d/ init . d/ named  start 
Stopping:  /etc/rc  . d/init . d/named  stop 
restarting:  /etc/rc.  d/init.  d/named  restart 

FreeBSD: 

For  Bind  9.3  and  up  (on  page  182): 

Starting:  /usr/local/etc/rc.  d/named,  sh  start 
Stopping:  /usr/local/etc/rc  . d/named,  sh  stop 
restarting:  /usr/local/etc/rc.  d/named.sh  restart 

For  Bind  8.x: 

Starting:  /usr/sbin/named  -u  named 
Stopping:  /usr/sbin/ndc  stop  -u  named 
restarting:  /usr/sbin/ndc  restart  -u  named 

Warning:  Without  “-u  named”,  the  command  will  run  under  root. 

Usually,  a Parallels  H-Sphere  DNS  server  contains  a cron  DNS  check  which  starts 
every  1 or  2 minutes  and,  if  named  is  not  started,  starts  it.  Therefore,  do  not  feel 
alarmed  if  you  stop  named  and  see  that  it  keeps  working  for  another  several  minutes. 
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This  section  outlines  some  peculiarities  of  Bind  9.3  in  comparison  with  Bind  8.x. 
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New  Features 

■ Bind  9.3  is  started/stopped/restarted  via  hsphere-daemontools-0.76-1 , the  package 
built  on  the  basis  of  DJB  daemontools  (http://cr.vp.to/daemontools.html).  This 
package  is  included  into  Parallels  H-Sphere  installation  and  is  used  with  the 
Parallels  H-Sphere  mail  service  (on  page  131)  package. 

■ The  named  daemon  is  administered  by  the  rndc  utility,  not  by  ndc. 

■ ndc  restart  is  no  longer  supported. 


Restarting  Bind 

Since  Bind  9.3,  the  Daemon  Tools’  svc  utility  is  called  in  the  named  daemon  to  stop, 
start  and  restart. 

The  procedure  of  stopping/starting/restarting  named  (on  page  45)  remains  the  same. 
However,  you  may  use  Bind  stop/start/restart  using  svc  as  an  alternative: 

Enter  the  /service  directory: 

cd  /service 

This  directory  is  used  by  daemontools  and  contains  symlinks  to  standard  service 
directories. 

> To  stop  Bind,  run: 

/command/ svc  -kd  named 

> To  start  Bind,  run: 

/command/svc  -u  named 

This  sequence  is  equivalent  to  restarting  named. 
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Using  rndc 

Bind  includes  a utility  called  rndc  which  allows  you  to  use  command  line  statements  to 
administer  the  named  daemon,  locally,  or  remotely. 

Managing  DNS  Zones 

> To  reload  a DNS  zone: 

rndc  reload  <ZONE> 

> To  reload  all  DNS  zones: 

rndc  reload 

After  that,  only  changed  zones  will  be  reloaded. 

> To  suspend  updates  to  a dynamic  zone: 

rndc  freeze  <ZONE> 

> To  enable  updates  to  a frozen  dynamic  zone  and  reload  it: 

rndc  thaw  <ZONE> 

Run  rndc  for  more  options. 

rndc  Config  File 

/etc/rndc.conf 

If  rndc  is  unable  to  connect  to  named,  check  the  /etc/rndc . conf  and 
/etc/named,  conf.  For  details  on  rndc  configuration,  run: 

rndc- conf gen 


WARNING:  It  is  strongly  unrecommended  to  manually  edit  the  configuration  files,  as  it 
may  lead  to  misconfiguration  in  dynamic  zone  updates!  Please  also  read  how  to 
customize  config  file  for  DNS  from  Appendix  C of  Parallels  H-Sphere  Installation  Guide. 
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Adding  DNS  Servers 

There  are  two  possible  options  to  set  up  DNS  servers: 

■ put  each  named  to  separate  boxes 

■ put  all  DNS  servers  to  one  box 

Note:  The  latter  option  requires  the  so-called  single  DNS  configuration.  For  more 
details,  click  here  (on  page  185). 


> To  add  Parallels  H-Sphere  DNS  server  to  a new  physical  box: 

1.  Prepare  the  box  for  DNS  service  installation  according  to  the 
instructions  from  Parallels  H-Sphere  Installation  Guide. 

2.  Download  and  run  the  installation  script  according  to  the  Adding 
Servers  and  Services  Guide. 

If  you  need  to  add  a DNS  server  to  a live  Parallels  H-Sphere  physical  server,  follow  the 
instruction  on  adding  services. 


Configuring  Single  DNS 

Single  DNS  configuration  enables  to  allocate  two  or  more  DNS  servers  on  one  physical 
box.  In  this  mode,  Parallels  H-Sphere  emulates  full-featured  DNS  configuration  where 
each  DNS  server  has  its  own  bound  IP.  This  allows  customers  with  a single  box 
installation  to  use  services,  such  as  OpenSRS  domain  registration,  that  require  at  least 
two  DNS  servers. 

WARNING:  Single  DNS  mode  is  available  only  if  all  DNS  servers  are  configured 
on  one  physical  box!  You  cannot  have  two  DNS  logical  servers  on  one  box  if  you 
have  another  DNS  server  on  a separate  box. 

To  put  an  extra  DNS  server  to  single  DNS  configuration: 

1.  Add  another  DNS  logical  server  to  the  physical  server  with  DNS  via  the 
interface  as  described  in  Parallels  H-Sphere  Service  Administrator 
Guide. 

2.  Log  in  as  cpanel  user  and  run  the  following  java  tools: 

■ ClusterPreparer: 

su  - cpanel  -c  "java  psoft.hsinst .boxes .ClusterPreparer" 

■ DNSCreator: 

su  - cpanel  -c  "java  psoft . hsphere . tools . DNSCreator  -m  rand" 
Read  more  about  DNSCreator  options  (on  page  194). 

3.  Execute: 

/hsphere/ local/ conf ig/bind/ scripts/ conf ig_bind 

4.  Restart  named  service. 
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Installing  and  Configuring  MyDNS 

MyDNS  is  a DNS  server  for  UNIX  that  serves  records  directly  from  an  SQL  database 
and  can  be  used  in  Parallels  H-Sphere  as  an  alternative  to  bind  (on  page  179). 
Currently  Parallels  H-Sphere  supports  MyDNS  to  work  only  with  MySQL. 

Installation 

> To  configure  Parallels  H-Sphere  to  work  with  MyDNS: 

1.  Download  the  latest  version  of  MyDNS  from  http://mydns.bbov.net. 

2.  Install  and  configure  MyDNS  version  that  is  served  by  MySQL  DB  on  a 
new  or  any  of  your  existing  Parallels  H-Sphere  servers  following  the 
MyDNS  installation  instructions 
(http://mydns.bbov.net/doc/html/mydns  2.html#SEC2). 

You  can  either  install  MyDNS  .rpm  package  or  compile  it. 

Warning:  Do  not  rename  the  ‘mydns’  MySQL  DB  created  during  the  installation. 

3.  Add  the  following  lines  into  the 

~cpanel / shi va/psof  t_conf  ig/hsphere  .properties  file: 

MYDNS_USER  = <login> 

MYDNS_PASS  = <password> 

MYDNS_DB_HOST  = <IP> 

Where: 

■ login  is  the  MySQL  user  name  to  access  MyDNS  MySQL  DB  with 
select/insert/update/delete  privileges.  You  will  need  to  create  one  more  MySQL 
user  than  is  described  in  MyDNS  installation  instructions  and  GRANT  ALL 
privileges 

■ password  is  the  password  for  MyDNS  user  login 

■ IP  is  the  IP  of  the  server  with  MySQL  DB  created  during  the  installation 

4.  In  the  admin  control  panel  check  if  MyDNS  name  server  is  listed  as  a 
server  group.  If  it’s  not,  log  into  the  system  database  (on  page  53)  and 
execute: 

INSERT  INTO  l_server_groups  (id,  type_id,  name)  VALUES  (21, 

2,  'MyDNS  name  server'); 

5.  Restart  your  CP  (on  page  41 ). 

6.  If  you  install  MyDNS  on  a new  server,  add  this  physical  server  as 
described  in  Parallels  H-Sphere  Service  Administrator  Guide. 

7.  Add  MyDNS  logical  server(s)  via  the  interface  with  the  MyDNS  name 
server  group  and  check  if  it  is  available  for  signup. 
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To  remove  Parallels  H-Sphere  DNS  service,  remove  the  ‘hsphere-bind’  package  by 
running: 

rpm  -e  hsphere-bind-XXX 


Note:  After  running  this  command,  commands  like  host,  dig,  nslookup  and  others  may 
disappear. 

Therefore,  it  is  recommended  that  afterwards  you  install  additional  packages:  bind- 
libs-XXX. rpm  and  bind-utils-XXX . rpm. 


Migrating  DNS  from  Bind  to  MyDNS 

> To  migrate  DNS  from  BIND  to  MyDNS: 

1.  Execute  steps'! -3  of  Installing  and  Configuring  MyDNS  (on  page  186). 
MyDNS  front  end  servers  must  be  installed  on  the  servers  where  you 
have  got  Parallels  H-Sphere  BIND  name  servers  installed. 

2.  Restart  CP  (on  page  41) 

3.  Log  to  CP  server  as  the  cpanel  user  (on  page  53) 

4.  To  transfer  DNS  zones  and  records  to  MyDNS,  run: 

java  psoft . hsphere . tools .MigratorToMyDNS  [-dz | --delete_zones] 

If  you  specify  -dz  or — deietezones  option,  then  the  utility  will  try  to  delete  each 
DNS  zone  on  the  new  set  of  DNS  logical  servers  before  recreating  them. 

5.  Restart  CP  (on  page  41). 

6.  Stop  Bind. 

7.  Add  external  DNS  server  to  /etc/resolv.conf  as  described  in  Appendix 
C.  Customizing  Configuration  Files  of  Parallels  H-Sphere  Installation 
Guide  for  each  MyDNS  server. 
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Moving  DNS 

DNS  servers  can  be  moved  only  to  Linux/Unix  boxes.  You  can’t  move  DNS  to  a 
Windows  platform. 

1.  Using  E.Manager,  create  a new  physical  server  and  add  the  DNS  server 
group  (or  add  this  group  to  the  physical  server  you  are  planning  to 
move  DNS  server  to). 

2.  Prepare  a new  box  with  DNS  using  Parallels  H-Sphere  installer. 

3.  Stop  the  Control  Panel  (on  page  41). 

4.  Log  into  the  system  database  (on  page  53)  and  run  the  following  DB 
queries: 

update  1 server  set  p server  id=[new  p server  id]  where 
id=[id  of  DNS  logical  server] ; 

update  1 server  ips  set  ip=' [new  DNS  server  IP] ' , 
mask=' [new  DNS  server  mask] ' where 

1 server  id=[id  of  DNS  logical  server]  and  flag=4; 
select  * from  1 server  ips  where 

1 server  id=[id  of  DNS  logical  server]  and  flag  in  (5,6); 

5.  Move  all  IPs  selected  from  Parallels  H-Sphere  database  (with  flags  5 
and  6)  to  the  new  server.  This  means  that  you  need  to  remove  these 
IPs  from  the  network  interface  on  the  old  DNS  server, 

/etc/named,  conf  (“Listen  on”  directive)  and 

/hsphere/ local/ network/ ips  files,  and  set  them  on  new  server 
(on  network  interface,  /etc/named . conf  and 
/hsphere/ local/ network/ ips  files). 

6.  Perform  this  step  ONLY  if  you  are  running  two  DNS  servers  on  one  box 
and  are  separating  them.  This  must  be  done  on  the  source  server. 

Go  to  the  directory  /hsphere/shared/scripts/MultiDNS/  and  copy  its 
contents  one  level  higher  overwriting  the  target  files: 

# cd  /hsphere/shared/scripts/MultiDNS/ 

# cp  . /*  . . / 

7.  Move  DNS  data.  You  can  choose  between  two  possibilities:  physical 
move  or  recreation  of  DNS  zones. 

■ Physical  move: 

1 . Move  the  /hsphere/local/var/named  directory  from  old  DNS  server  to  the  new 
server. 

2.  Change  the  ownership  of  moved  files  to  namedmamed: 
chown  -R  named: named  /hsphere/local/var/named 

3.  On  the  rest  of  DNS  servers,  for  slave  zones  which  had  masters  set  to  the  old 
DNS  server  IP,  change  it  to  the  new  DNS  server  IP  (using  sed  or  any  other 
method). 

4.  Restart  named  (on  page  45). 

■ DNS  recreation  tool: 

1 . Log  into  your  CP  server  as  the  cpanel  user  (on  page  53). 
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2.  Execute  the  following  command  (it  may  take  a while  if  you  have  many  DNS 
zones): 

java  psoft.hsphere. tools. DNSCreator  -m  db  -dz 

8.  Start  the  Control  Panel  (on  page  41).  You  can  safely  delete  the  unused 
Logical  DNS  server  created  in  step  2. 

9.  Change  the  IP  in  A DNS  record  for  the  DNS  server  in  the  service  DNS 
zone  (using  the  Control  Panel). 
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Removing  Broken  DNS  Zones 

This  document  contains  step-by-step  instruction  on  how  to  remove  the  DNS  zone  if, 
while  adding  DNS  zone  for  a domain,  the  following  error  message  shows  up: 

Zone  ...  has  been  taken 


See  also  the  troubleshooter 

(http://hsphere.parallels.com/HSdocumentation/FAQ/troubleshooter.php). 

Note:  Here,  we  deal  with  such  issues  where,  by  some  reason,  DNS  zone  was  not 
correctly  created  or  not  completely  removed  from  the  system.  We  do  not  consider 
cases  where  this  DNS  zone  exists  on  a live  account. 

First  of  all,  you  need  to  check  from  the  CP  interface  if  this  domain  zone  is  indeed 
removed.  For  this,  choose  the  Search/In  resellers  menu  and  search  for  the  domain  name. 

If  no  account  is  found,  you  need  to  remove  the  DNS  zone  from  the  Parallels  H-Sphere 
database. 

1 . We  strongly  recommend  you  to  back  the  database  up  before  you  make  changes  in 
it. 

2.  Use  transactions  when  you  modify  tables.  Transactions  have  the  following  format: 
begin;  - start  the  transaction,  [statements  for  modifying  data:  delete,  insert, 
update,  and  the  like] 

rollback;  - rollback  the  transaction;  also  perform  rollback  when  you  make  a 
syntax  error  in  the  previous  statement, 
commit;  - commit  the  transaction. 

Use  either  rollback;  or  commit;  to  finish  the  transaction. 

The  following  tables  and  fields  are  considered  in  this  guide: 

■ dns_zones  - the  list  of  DNS  zones. 
dns_zones . id  - DNS  zone  resource  identifier; 
dns_zones  .name  - DNS  zone  domain  name. 

■ parent_chiid  - the  tree  of  resources  related  to  accounts.  Account  is  a root 
resource.  Certain  account  resources  (parent  resources)  may  have  child  resources. 
parent_child.  account_id=accounts  . id  - account  identifier; 
parent_chiid. parent_id  - parent  resource  identifier; 
parent_chiid.  chiid__id  - child  resource  identifier.  DNS  zone  is  a child 
resource  to  the  account. 

■ accounts  - the  list  of  accounts, 
accounts . id  - account  identifier; 

account . deleted  - contains  the  date  when  the  account  has  been  deleted,  or 
NULL  if  the  account  is  alive; 

■ users  - the  list  of  end  users, 
users . id  - user  id; 
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users . reseller  id=reseiiers . id  - id  of  the  reseller  under  whom  this  user  is 
created;  1 if  the  user  has  no  reseller. 

■ user_account  - the  table  which  maintains  the  user-account  correspondence.  It 
links  the  users  and  accounts  tables. 

user_account . user_id=users  . id  - user  id; 

user_account . account_id=accounts  . id  - account  id  for  this  user. 

■ resellers  - the  list  of  resellers, 
resellers  . id  - reseller  id. 

■ e_zones  - the  list  of  service  DNS  zones. 

e zones.  id=dns  zones  . id  - service  DNS  zone  id; 

e zones  . reseller  id=resellers  . id  - id  Of  the  reseller  who  hosts  this  zone. 

1.  Check  if  the  DNS  zone  is  present  in  the  database: 

select  * from  dns_zones  where  name  = 'domain.com'; 

Here,  domain . com  is  the  DNS  zone  name. 

2.  Find  out  the  type  of  the  DNS  zone  (user  DNS  zone  or  service  DNS 
zone). 

select  account_id  from  parent_child  where  child_id  = 
<dns_zone_id>  ; 

If  the  query  returns  nothing,  the  DNS  zone  is  the  service  DNS  zone. 

Otherwise,  it  is  the  user  DNS  zone.  parent_chiid.  account_id  is  the  account 
under  which  this  DNS  zone  is  created. 

In  this  section: 


Removing  User  Domain  Zone 192 

Removing  Service  Domain  Zone 193 
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Removing  User  Domain  Zone 

1.  Check  if  the  account  for  the  DNS  zone  is  deleted: 

select  deleted  from  accounts  where  id  = <account_id>; 

2.  If  accounts  . deleted  is  not  null,  it  means  that  the  account  has  been 
deleted. 

In  this  case,  it  is  required  to  remove  all  records  with  this  account  id  from  the 

parent_child  table: 

begin; 

delete  from  parent  child  where  account  id  = <account  id>  and 

account  id  <>  child  id; 

commit; 

3.  If  account . deleted  is  null,  check  if  there  is  a user  for  this  account: 
select  * from  user_account  where  account_id  = <account_id>; 

If  this  query  returns  nothing,  we  have  got  an  error:  account  exists,  but  no  user 
corresponds  to  this  account.  In  this  case,  you  should  run  the  DeietedAccounts 
Java  utility: 

1 . Log  into  your  control  panel  server  as  cpanel  user  running  the  following 
command: 

su  -1  cpanel 

2.  Execute  the  following  command: 

java  psof t . hsphere . tools . DeleteAccounts 

Then,  enter  the  ids  of  the  accounts  you  wish  to  delete,  or  create  the  file  with  these 
account  ids  in  separate  lines  and  redirect  it  to  the  standard  input  of  the  above 
command: 

3.  Make  sure  you  are  logged  as  cpanel  user. 

4.  Execute  the  following  command: 

java  psof t. hsphere . tools . DeleteAccounts  < 
file  with  account  ids 


Note:  DeleteAccounts  should  not  be  used  against  reseller  accounts! 
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Removing  Service  Domain  Zone 

1.  Find  the  reseller  id  for  this  DNS  zone: 

select  reseller_id  from  e_zones  where  id  = <dns_zone_id>; 

2.  Find  the  reseller  in  the  resellers  and  users  table: 

select  * from  resellers  where  id  = Creseller  id>; 
select*  from  users  where  id  = Creseller  id>; 

3.  If  the  reseller  is  not  found  in  any  of  these  tables: 

1 . Change  the  reseller  id  to  1 in  the  e_zones  table: 
begin; 

update  e zones  set  reseller  id  = 1 where  id  = <dns  zones  id>; 
commit; 

2.  Restart  CP. 

3.  Remove  the  DNS  zone  from  the  CP  admin  interface  in  the  E. Manager/DNS  Settings 
menu. 
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Using  DNS  Creator 

DNS  Creator  is  a utility  that  re-creates  DNS  data  to  new  DNS  servers.  Use  this  utility  to 
republish  DNS  data  to  a different  box  or  add  an  extra  DNS  server. 

> To  create  DNS: 

1.  Log  into  your  control  panel  server  as  the  cpanel  user  (on  page  53). 

2.  Run  DNS  Creator: 

java  psoft . hsphere . tools . DNSCreator  -m  creat±on_method  [-dz] 
[-z  zonename ] 

• m creation  method.  Possible  values:  db  or  rand 

■ db  - pick  NS  servers  as  they  are  defined  in  the  Parallels  H-Sphere  database 

■ rand  - pick  NS  servers  randomly 

• dz  | — deiete_zones  - delete  zones  first.  Add  this  option  only  if  such  zones 
already  exist.  With  this  option,  DNS  creation  will  take  at  least  twice  more  time. 

• lids  | — logical-servers  - process  zones  which  are  on  the  logical  servers 
with  the  specified  IDs. 

• pip  | — pServeriP  - specifies  a physical  server  by  its  primary  IP.  All 
necessary  logical  server  IDs  are  chosen  automatically.  Often  -p/p  is  used  as  an 
alternative  to  -lids. 

• z | — zone  - recreate  only  one  specified  zone.  Without  this  option,  all  zones 
will  be  recreated. 

Note:  If  both  lids  and  -z  parameters  are  specified,  the  -z  parameter  will  be 
ignored. 


Note:  If  you  are  adding  an  extra  DNS  server,  specify  -m  rand  or  else  this  new  DNS 
server  will  be  available  only  for  new  signups. 

Please  be  patient.  If  you  have  hundreds  of  domains,  this  utility  might  take  hours  to 
have  executed. 


Chapter  15 


MySQL  Server 


This  chapter  describes  some  task  you  may  need  to  perform  on  your  Parallels  H-Sphere 
MySQL  server. 

MySQL  server  log  file  is/var/iog/mysqid. 

MySQL  comes  with  PhpMyAdmin  (http://www.phpmvadmin.net/)  which  is  a MySQL 
administration  Web  interface  written  in  PHP.  It  is  installed  as  an  hsphere- 
phpmyadmin-<vers/on>-<bu/7d>  package,  where  <version>  is  PhpMyAdmin  version,  and 
<build>  is  this  package’s  build  number. 

PhpMyAdmin  installation  directory  is 

/hsphere/ shared/ apache/htdocs /phpMyAdmin. 


In  this  chapter: 
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Running  Parallels  H-Sphere  MySQL  Scripts 197 

Getting  Remote  Access  to  MySQL  Logical  Server 198 

Enabling  Linked  Tables  in  phpMyAdmin 199 

Changing  MySQL  Root  Password 200 

Moving  MySQL 202 

Moving  MySQL  Accounts 205 


Installing  MySQL  Server 

1.  Add  MySQL  server  to  Parallels  H-Sphere  cluster  as  described  in  Adding 
Servers  and  Services  Guide. 

2.  Optionally,  configure  default  MySQL  password  hash  length  to  be 
chosen  when  clients  create  MySQL  database  users. 

To  make  long  41 -byte  hash  length  chosen  by  default,  add  the  following 
line  to  ~cpanel/shiva/psoft_config/hsphere. properties: 

MYSQL_DEFAULT_LONG_PASSWORD_HASH=TRUE 

The  above  parameter  controls,  which  hash  length  is  chosen  by  default 
in  the  web  form  ‘Create  MySQL  user’.  User  can  still  select  either  short 
hash,  or  long  hash. 
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Backing  Up  MySQL  Database 

To  back  up  MySQL  database,  back  up  the  MySQL  home  directory,  or  use  the 
mysqldump  Utility  to  dump  the  database.  Type  ‘man  mysql’,  ‘man  mysqldump’  or 
see  MySQL  documentation  (http://www.mysql.com/documentation/)  for  details. 
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Running  Parallels  H-Sphere  MySQL 
Scripts 

On  the  MySQL  database  box  the  following  scripts  are  installed  in 

/hsphere/ shared/ scripts: 

mysql-change-user-password  - Changes  user  password 
mysql-change-user-password.  sh  - changes  user  password 
mysqi-db-size  - calculates  database  size 
mysqi-db-size  .pi  - calculates  database  size 
mysql-drop-database  - drops  database 
mysql-drop-database  . sh  - drops  database 
mysqi-resume-user  - resumes  suspended  user 
mysqi-resume-user . sh  - resumes  suspended  user 
mysqi-create-db  - creates  database 
mysqi-create-db . sh  - creates  database 

mysqi-db-users  - lists  MySQL  database  users  who  have  any  privilege  on  this 
database 

mysqi-db-users . sh  - lists  MySQL  database  users  who  have  any  privilege  on  this 
database 

mysqi -get -login . pi  - gets  superuser  login  and  password 
mysqi -get -login . pi . sh  - gets  superuser  login  and  password 
mysqi -revoke-ail  - revokes  all  user  privileges  on  database 
mysqi-revoke-aii . sh  - revokes  all  user  privileges  on  database 
mysqi-create-user  - creates  MySQL  user 
mysqi-create-user . sh  - creates  MySQL  user 
mysqi-deiete-user  - deletes  MySQL  user 
mysqi-deiete-user . sh  - deletes  MySQL  user 

mysqi -grant -priv  - grants  given  privilege  on  given  database  to  given  user 
mysqi-grant-priv . sh  - grants  given  privilege  on  given  database  to  given  user 
mysqi-suspend-user  - suspends  MySQL  user 

mysql-suspend-user . sh  - suspends  MySQL  user 

All  scripts  accept  some  command  line  parameters.  All  scripts  consist  of  two  parts.  The 
first  part,  typically  without  extension,  sets  some  necessary  variables  and  then  calls  out 
the  second  part  of  the  script  under  sudo. 

INFO:  f ix_perm.  sh  scripts  sets  the  needed  owner  and  rights  to  mysqi  scripts. 

WARNING:  Some  of  these  scripts  are  different  on  the  FreeBSD  systems,  so  copy  the 
corresponding  script  versions  from  /hsphere/ shared/ scripts/FreeBSD. 
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Getting  Remote  Access  to  MySQL  Logical 
Server 


By  default,  MySQL  client  connects  to  MySQL  server  on  localhost  (127.0.0.1).  It  is 
possible  to  configure  MySQL  client  to  use  the  -h  option  to  connect  to  the  MySQL 
server  remotely  by  the  logical  server  IP: 

mysql  -h  <mysql_logical_server_ip> 

This  feature  is,  in  particular,  required  in  some  custom  MySQL  configurations  where  one 
MySQL  client  (bound  to  the  physical  server  IP)  connects  to  several  MySQL  servers  on 
different  boxes  (bound  to  the  logical  server  IPs). 

> To  enable  or  disable  remote  access  to  particular  MySQL  logical  servers  in 
the  Control  Panel: 

1.  Go  to  the  admin  Control  Panel,  E. Manager  menu,  L.Server. 

2.  Choose  a MySQL  logical  server  from  the  list  of  logical  servers. 

3.  Under  Additional  Options,  check  or  uncheck  the  option  Remote  Access  To 

MySQL  Server  and  press  Set: 

F — ... — 


4.  Confirm  your  choice  on  the  page  that  appears. 

WARNING:  1)  Remote  access  to  MySQL  server  is  currently  incompatible  with  Parallels 
H-Sphere  mail  system!  You  must  not  enable  remote  MySQL  access  on  physical 
servers  with  live  mail! 

2)  You  must  not  change  logical  server  IP  on  or  add  another  server  IP  to  MySQL 
logical  server  where  remote  access  is  enabled  to! 
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Enabling  Linked  Tables  in  phpMyAdmin 

Newer  versions  of  phpMyAdmin  give  the  following  error  if  not  configured  accordingly: 
“Error 

The  additional  features  for  working  with  linked  tables  have  been  deactivated.” 

These  features  include  bookmarks,  comments,  SQL-history,  PDF  generation,  field 
contents  transformation,  etc. 

> To  enable  new  phpMyAdmin  features: 

1.  Log  into  the  web  server  as  root.  This  must  be  the  web  server  where 
phpMyAdmin  is  installed.  The  ID  of  this  logical  server  is  specified  in 

/hsphere/ local /home/ cpanel / shiva/ psof t_conf ig/hsphere 

.properties  on  the  CP  server. 

2.  Create  phpmyadmin  database.  If  you  are  running  Web  and  MySQL 
servers  on  the  same  box: 

mysql  -u  root  -p<password>  < 

/hsphere/ shared/apache/htdocs/phpMyAdmin/ scripts/ create_table 
s . sql 

If  they  are  on  different  boxes: 

mysql  -h  <MYSQL_SERVER_IP>  -u  root  -p<PASSWORD>  < 

/hsphere/ shared/apache/htdocs/phpMyAdmin/ scripts/ create_table 
s . sql 

3.  Give  necessary  permissions  to  the  controluser. 

If  you  are  running  Web  and  MySQL  servers  on  different  boxes,  first  log  into  the 
MySQL  server  as  root. 

mysql#  GRANT  SELECT,  INSERT,  UPDATE,  DELETE  ON  phpmyadmin.* 

TO  'phpuser' @ ' %' ; 

4.  Enter  the  following  values  in  the  file 

/hsphere/ shared/ apache /ht docs / phpMyAdmin/ config.inc.p 

hp  on  the  web  server: 

$cf gServers [ 1 ] ['pmadb']  = 'phpmyadmin'; 

$cf gServers [ 1 ] ['table  info']  = 'pma  table  info'; 

$cf gServers [ 1 ][' pdf_pages ' ] = 'pma_pdf_pages' ; 

$cf gServers [ 1 ] ['history']  = 'pma  history'; 

$cf gServers [ 1 ] ['column  info']  = 'pma  column  info'; 

$cf gServers [ 1 ][' table_coords ' ] = 'pma_table_coords'; 

$cf gServers [ 1 ] ['relation']  = 'pma  relation'; 

$cf gServers [ 1 ] [ ' bookmarktable ' ] = 'pma  bookmark'; 
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Changing  MySQL  Root  Password 

This  document  explains  how  to  change  the  root  user  password  in  MySQL  access 
privilege  database. 

In  this  section: 
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Option  1 

1.  Login  as  root  to  the  box  with  the  MySQL  server. 

2.  Stop  MySQL  server  (on  page  44). 

3.  Open  the  mysql  server  startup  script.  This  is  the  file  you  have  just 
executed  to  stop  MySQL  server. 

4.  Find  the  line  that  contains  the  mysqld_safe  command  and  add — skip- 
grant-tables  as  its  parameter. 

5.  Start  MySQL  server  (on  page  44). 

6.  Login  as  the  mysql  user  and  connect  to  the  mysql  user/permission 
database  and  run  the  update  queries: 

# mysql  -u  root  mysql 

mysql>  UPDATE  user  SET  Password=PASSWORD ( 'newrootpassword' ) 
WHERE  User='root' ; 
mysql>  FLUSH  PRIVILEGES; 

replacing  newrootpassword  with  the  new  root  password  to  the  box  with  the 
MySQL  server. 

7.  Exit  mysql  database  by  typing  \q. 

8.  Exit  mysql  user  console  by  typing  exit. 

9.  Stop  MySQL  server  (on  page  44). 

10. Open  the  mysql  server  startup  script  and  remove  the — skip-grant- 
tables  parameter  you  added  above. 

11. Start  MySQL  server  (on  page  44). 

12. Open  the  file  -mysql/  .my.  cnf  and  update  the  password  in  the 
corresponding  line. 
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Option  2 

1.  Stop  the  MySQL  daemon: 

kill  'pidof  mysqld' 

ps  auxw  | grep  mysql 

2.  Temporarily  create  a text  file  in  the  following  location: 

/hsphere/ local/ config/ mysql/ f ile_name 

This  file  must  contain  a string  with  an  sql  command  similar  to  this  one: 

SET  PASSWORD  FOR  'root' @ ' localhost'  = 

PASSWORD ( 'your_new_mysql_password' ) ; 

3.  Manually  start  mysql  with  a special  option: 

mysqld_safe— init-file=/hsphere/local/ conf ig/mysql/ file_name  & 

4.  Check  whether  the  new  password  is  working: 

mysql  -p 

If  everything  is  fine,  you’ll  get  a screen  like  this: 

Welcome  to  the  MySQL  monitor.  Commands  end  with  ; or  \g. 

Your  MySQL  connection  id  is  2 to  server  version:  5.0.27- 
standard-log 

Type  'help;'  or  '\h'  for  help.  Type  '\c'  to  clear  the  buffer. 

5.  Kill  mysql: 

kill  'pidof  mysqld' 

6.  Remove  the  temporary  file: 

rm  -f  /hsphere/local/config/mysql/file_name 

7.  Start  MySQL  server  (on  page  44). 

8.  Open  the  file  -mysql/  .my.  cnf  and  update  the  password  in  the 
corresponding  line. 

This  option  2 is  simpler,  faster  and  more  secure  than  the  first  one  as  there  is  neither 
editing  the  script  rc . d/mysqid  startup  nor  using  the  command — skip-grant- 
tables. 
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Moving  MySQL 


This  section  explains  how  to  move  MySQL  service  between  boxes  of  an  Parallels  H- 
Sphere  cluster. 

In  this  section: 


Step  1 . Preparing  Servers 202 

Step  2.  Moving  MySQL  Content 202 

Step  3.  Updating  System  Database 203 

Step  4.  Updating  Resellers’  Server  Aliases 203 

Step  5.  Synchronizing  MySQL  Content 203 

Step  6.  Finalizing  the  Migration 204 

Step  7.  Checking  Functionality 205 


Step  1 . Preparing  Servers 

1.  Update  your  Parallels  H-Sphere  to  the  latest  version. 

2.  Apply  the  latest  MySQL  update,  if  any,  after  the  installation  of  your 
Parallels  H-Sphere. 

3.  Prepare  a new  box  with  MySQL  (on  page  195)  using  Parallels  H-Sphere 
installer. 

4.  In  E.Manager,  disable  signup  for  the  MySQL  server. 


Step  2.  Moving  MySQL  Content 

Note:  You  can  move  DB  content  using  rsync  only  if  the  source  and  target  boxes  have 
the  same  DB  server  and  OS  versions,  including  architecture  (32/64bit).  If  that  is  not  the 
case,  it  is  recommended  to  move  content  using  the  DB  server’s  built-in  backup/restore 
utilities  in  Step  5 and  skip  Step  2. 

1.  Log  into  the  target  box  as  root: 
ssh  root @<TARGET_DB_SERVER_IP> 

2.  Stop  MySQL  service  (on  page  44). 

3.  Move  the  mysql/  directory  from  the  source  server: 

rsync  -arzgop  -e  ssh  rootQ<SOURCE_DB_SERVER_IP> : ~mysql/  ~mysql/ 

4.  Start  MySQL  service  (on  page  44). 
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Step  3.  Updating  System  Database 

1.  Stop  the  Control  Panel  (on  page  41). 

2.  Log  into  the  Parallels  H-Sphere  system  database  (on  page  53)  and  run 
the  following  queries: 

update  1 server  set  p server  id=<TARGET  PHYSICAL  SERVER  ID> 
where  id=<DB_LOGICAL_SERVER_ID>; 

(1  record) 

update  1 server  ips  set  ip='<TARGET  DB  SERVER  IP>' , 
mask=' <TARGET_DB_SERVER_MASK> ' where 
l_server_id=<DB_LOGICAL_SERVER_ID>  and  flag=4; 

(1  record) 

3.  Start  the  Control  Panel  (on  page  41). 


Step  4.  Updating  Resellers’  Server  Aliases 

As  the  cpanel  user,  run  ServerAliasRenamer: 

java  psof t . hsphere . tools . ServerAliasesRenamer— lserver 

<DB_LOGICAL_SERVER_ID> 

Step  5.  Synchronizing  MySQL  Content 

1.  Stop  MySQL  service  on  the  source  box. 

2.  Repeat  all  of  Step  2 above  if  the  source  and  target  boxes  have  the 
same  DB  server  and  OS  versions,  including  architecture  (32/64bit). 
Otherwise,  use  the  DB  server’s  built-in  utilities  for  DB  content  moving 
while  limiting  access  to  both  DB  servers  for  the  end  users.  You  may 
also  need  to  restore  the  root  user  password  for  MySQL  either  by 
copying  it  from  the  source  server  (the  password  is  stored  in 
/var/db/mysq/.my.cnf  on  FreeBSD,  /var/lib/mysql/.my.cnf  on  Linux),  or 
launch  the  /hsphere/local/config/mysql/scripts/config_mysql  utility  on 
the  target  server  with  root  privileges. 

3.  If  the  source  box  has  a mail  service,  log  in  there  and  start  MySQL 
service. 
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Step  6.  Finalizing  the  Migration 

1.  Go  to  E.Manager  ->  DNS  Manager  and  choose  to  edit  the  main  service  DNS 
zone.  Change  the  IP  in  the  A DNS  record  for  the  MySQL  server. 

2.  Open  the  file  /servers  . conf  ig . php  in  the  PhpMyAdmin  directory. 
Change  the  IP  of  MySQL  server  in  $cfgServers  [$i]  [ ' host'  ] ■ $i 
is  the  number  of  the  MySQL  server  in  PhpMyAdmin  configuration: 

$1=1,2, . . 

3.  Check  if  any  of  the  customer  scripts  use  the  MySQL  server  IP  and 
update  all  instances. 

4.  Install  (http://www.quietsche-entchen.de/download/tcpproxy-2.0.0- 
beta15.tar.qz)  and  configure  (http://www.quietsche-entchen.de/cqi- 
bin/wiki.cqi/-wiki/proxies/TcpProxy)  TCP  proxy  on  the  old  server  to 
ensure  that  MySQL  hostname  resolves  to  the  new  IP  address  during 
the  propagation  period. 

5.  You  can  safely  delete  the  unused  Logical  Server  created  during  Step  1. 
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Step  7.  Checking  Functionality 

Now  that  you  have  finished  the  migration,  visit  a few  user  websites  that  use  MySQL 
and  verify  that  everything  works  smoothly. 


Moving  MySQL  Accounts 


WARNING:  The  undermentioned  procedure  is  recommended  for  experienced  Parallels 
H-Sphere  owners  only! 

All  MySQL  resources  of  the  particular  Parallels  H-Sphere  account  are  called  MySQL 
account  hereinafter.  The  following  steps  explain  how  to  move  all  databases  of  a 
particular  Parallels  H-  Sphere  account  to  a new  logical  MySQL  server  and  apply 
changes  to  the  Parallels  H-Sphere  database. 

> To  move  MySQL  account: 

1.  Log  into  the  source  MySQL  server  and  get  MySQL  root  password  that 
will  be  generated  after  entering  the  following  command: 

# cat  ~mysql/ .my . cnf 

2.  Export  user  account  databases  on  source  MySQL  server  with  the  help 
of  mysqldump  utility: 

# mysqldump  -Q  -uroot  -p  DBNAME  > DBNAME . sql 
where  dbname  is  the  database  name. 

This  should  be  applied  to  every  user  database  within  the  account. 

3.  Dump  user  database  privileges  on  source  MySQL  server: 

# mysqldump  -c  -e  -Q  -t  my sql  -uroot  -p  db  -w  "db  like 
'USERNAME_% ' " > USERNAME_mysql . db . sql 

where  username  is  an  Parallels  H-Sphere  user  prefix  for  database. 

4.  Log  into  CP  server.  Change  MySQL  logical  server  id  for  the  account: 

# su  - cpanel 

# java  -Xms64M  -Xmx256M  psoft . hsphere . tools . ChangeLServerld  - 
a ACC_ID— from  OLD_LID-to  NEW_LID 

where: 

acc  id  - the  account  id 

old_lid  - source  logical  mysql  server  ID 

new_lid  - target  mysql  logical  server  ID 

5.  Create  empty  databases  on  the  target  MySQL  server: 

# su  - cpanel 

# java  -Xms64M  -Xmx256M  psoft . hsphere . tools . PhysicalCreator  - 
rg  mysql  -co  -lid  NEW_LID  -accs  ACC_ID 

6.  T ransfer  all  dbname  . sql  and  usERNAME_my sql . db . sql  files  from 
the  source  server  to  the  target  MySQL  server. 

7.  Log  into  the  target  MySQL  server  and  get  MySQL  root  password  that 
will  be  generated  after  entering  the  following  command: 
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# cat  ~mysql/ .my . cnf 

8.  Import  databases: 

# mysql  -uroot  -p  DBNAME  < DBNAME . sql 

9.  Restore  user  database  privileges: 

# mysql  -uroot  -p  mysql  < USERNAME_mysql . db . sql 

# mysqladmin  reload  -p 

10.  Restart  Parallels  H-Sphere  CP  (on  page  41). 

11.  Make  sure  to  check  MySQL  dbs  functionality  on  the  target  server.  If  it  is 
ok,  you  may  delete  MySQI  databases  from  the  source  server  by  running 
the  following  commands: 

/hsphere/ shared/ scripts/mysql-drop-database  DBNAME 
/hsphere/ shared/ scripts/mysql-delete-user  USERNAME 

Perform  steps  2, 3, 8, 9,1 1 for  each  MySQL  db  and  user  of  the  current  Parallels  hl- 
Sphere  account  on  the  source  MySQL  server. 


Chapter  16 


PostgreSQL  Server 


This  chapter  describes  some  task  you  may  need  to  perform  on  your  Parallels  H-Sphere 
PostgreSQL  server. 

PostgreSQL  log  file  is  /var/iog/pgsqi. 

PostgreSQL  server  comes  with  PhpPgAdmin  (http://phppqadmin.sourceforge.net/) 
which  is  a PostgreSQL  administration  Web  interface  written  in  PHP.  It  is  installed  with 
PostgreSQL  server  as  a hsphere-phppgadmin-<vers/'on>-<bu/7c/>  package,  where 
<version>  is  PhpPgAdmin  version,  and  <build>  is  this  package’s  build  number. 

IPhpPgAdmin  installation  directory  is 

/hsphere/ shared/ apache/htdocs/phpPgAdmin. 


In  this  chapter: 


Configuring  PostgreSQL 208 

Backing  Up  PostgreSQL  Database 209 

Using  VACUUM  Utility 209 

Running  PostgreSQL  Scripts 210 

Changing  Postgres  User  Password 211 
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Moving  PostgreSQL 212 
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Choosing  Remote  Web  Logical  Servers  for  phpMyAdmin/phpPgAdmin  Frontends214 
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Configuring  PostgreSQL 

1 . Prior  to  configuration,  you  need  to  start  PostgreSQL  for  the  first  time  to  initialize  the 
PostgreSQL  service  database  and  to  create  the  necessary  files  and  directories. 

On  RedHat  servers,  PostgreSQL  service  is  initialized  automatically  on  the  first 
PostgreSQL  start: 

/ etc/rc . d/init . d/postgresql  start 

On  FreeBSD  servers,  you  need  to  initialize  it  manually  before  you  start  PostgreSQL: 
su  - pgsql  -c  initdb 

/usr/local/etc/rc . d/010 .pgsql . sh  start 

2.  To  configure  the  access  to  PostgreSQL  DBs,  go  to  PostgreSQL  home  directory.  It 
is  usually  /usr/iocai/pgsqi.  To  find  out  what  is  the  path  to  PostgreSQL  home 
directory,  login  as  postgres  user  under  root  and  type  pwd: 

# su  - postgres 

# pwd 

or,  finger  postgres  to  get  info  about  the  postgres  user: 

# finger  postgres 


In  this  directory,  find  the  data/pg_hba.  conf  file.  Open  it  and  find  the  records  similar 
to  the  ones  below: 


TYPE 

DATABASE 

USER 

IP_ADDRESS 

MASK 

AUTHTYPE 

MAP 

local 

all 

all 

trust 

host 

all 

all 

127.0.0.1 

255.255.255.255 

password 

host 

all 

all 

0. 0.0.0 

0.0. 0.0 

password 

If  the  ‘authtype’  parameter  is  set  to  trust,  you  must  change  the  authentication 
option  to  password. 

■ For  more  detailed  configuration,  see  pg_hba . conf  file. 

Warning:  If  during  the  update  process  you  get  the  message: 

WARNING:  pg_hba.conf  must  be  configured  more  strictly. 

it  means  that  pg_hba . conf  for  a given  Postgres  database  should  be  configured  to 
restrict  IP  access  to  Postgres  databases  from  outside  the  Parallels  H-Sphere  cluster.  It 
is  especially  important  to  ensure  that  IP  access  to  the  Parallels  H-Sphere  system 
database  is  provided  only  from  CP. 

See  also:  Setting  password  for  the  PostgreSQL  user  (on  page  21 1 ) (postgres  on 
RedHat,  pgsql  on  FreeBSD). 
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Backing  Up  PostgreSQL  Database 

Back  up  the  PostgreSQL  home  directory  or  make  the  database  export  by  the  means  of 
PostgreSQL.  Type  ‘man  psqi’  or  see  Postgres  documentation 
(http://www.postaresal.org/docs/)  for  details. 


Using  VACUUM  Utility 

The  Postgres  VACUUM  command  enables  to  clean  up  the  server  transactions. 
Enter  the  psql  server: 

# psql  database_name  [user_name] 

In  the  psql  command  line,  type  the  ‘vacuum  full’  command: 

vacuum  full; 

Or,  write  a shell  script  performing  this  procedure  and  add  it  to  cron  jobs  on  the 
PostgreSQL  server  to  be  launched  regularly. 

Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete! 
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Running  PostgreSQL  Scripts 

On  the  PostgreSQL  database  box  in  the  /hsphere/shared/scripts  directory,  the 
following  scripts  are  installed: 

pgsql-change-user-password  - Changes  user  password 
pgsql-change-user-password.  sh  - changes  user  password 
pgsqi-create-db  - creates  PostgreSQL  database 
pgsqi-create-db . sh  - creates  PostgreSQL  database 
pgsqi-create-user  - creates  PostgreSQL  user 
pgsqi-create-user . sh  - creates  PostgreSQL  user 
pgsqi-db-size  - calculates  database  size 
pgsqi-db-size  .pi  - calculates  database  size 
pgsqi-deiete-user  - deletes  PostgreSQL  user 
pgsqi-deiete-user . sh  - deletes  PostgreSQL  user 
pgsqi-drop-database  - drops  PostgreSQL  database 
pgsqi-drop-database . sh  - drops  PostgreSQL  database 
pgsqi -get-login  - gets  PostgreSQL  superuser  login  and  password 
pgsqi -get-login. pi  - gets  PostgreSQL  superuser  login  and  password 
pgsqi-resume-user  - resumes  the  suspended  user 
pgsqi-resume-user . sh  - resumes  the  suspended  user 
pgsqi-setenv  - sets  PostgreSQL  environment  variables 
pgsqi-suspend-user  - suspends  PostgreSQL  user 
pgsqi-suspend-user . sh  - suspends  PostgreSQL  user 

All  scripts  accept  some  command  line  parameters.  All  scripts  consist  of  two  parts.  The 
first  part,  typically  without  extension,  sets  necessary  variables  and  then  calls  the 
second  part  of  the  script  under  sudo. 

INFO:  f ix_perm.  sh  scripts  sets  needed  owner  and  rights  to  Postgres  scripts. 

WARNING:  Some  of  these  scripts  are  different  on  FreeBSD  systems,  so  copy 
corresponding  versions  Of  scripts  from  /hsphere/shared/scripts/FreeBSD. 
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Changing  Postgres  User  Password 

Changing  the  password  for  the  postgres  user  (pgsqi  in  FreeBSD)  differs  depending 
on  the  version  of  PostgreSQL  installed.  To  check  the  version,  type  under  root: 

# psql— version 

PostgreSQL  7.4  is  used  in  the  latest  versions  of  Parallels  H-Sphere  for  both  the 
Parallels  Fi-Sphere  system  database  (on  page  51)  and  user  databases  (on  page  207). 

The  postgres/pgsqi  password  is  changed  in  the  PostgreSQL  service  database.  This 
is  a more  secure  way  than  having  the  passwords  stored  in  a file. 

1 . Run  under  root: 

In  RedHat: 

psql  -d  tempiatei  -u  postgres  (enter  the  templatel  service  database) 

alter  user  postgres  with  password  'postgres  password' ; (run 
query  to  change  the  password) 

In  FreeBSD: 

psql  -d  templatel  -U  pgsqi 

alter  user  pgsqi  with  password  'pgsqi  password' ; 

2.  Restart  Postgres  (on  page  42)  to  apply  changes. 
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Localizing  PostgreSQL 

> To  set  up  a custom  language  support  when  entering  data  into 
PostrgreSQL: 

1.  Recompile  PostgreSQL  using  the  following  keys: 

• enable-locale  (enable  locale  support) 

— enable-recode  (enable  Cyrillic  recode  support) 

— with-mb=wiN  (enable  multi-byte  support,  e.g.  WIN) 

2.  Create  Parallels  H-Sphere  database  supporting  the  new  encoding  (e.g. 
WIN). 

NOTE:  if  the  browser  encoding  does  not  agree  with  the  database  encoding,  it  is 
impossible  to  guarantee  a correct  record  in  the  database. 

In  the  ~cpanel/ shiva/psoft  conf  ig/hsphere  .properties  configuration  file, 
replace 

DB_URL  = j dbc : postgresql : //127 . 0 . 0 . 1/hsphere 

with 

DB_URL  = 

j dbc : postgresql : / /127 .0.0.  l/hsphere?charSet  =<YOUR_LANGUAGE_ENCODIN 
G> 

For  instance,  Russian  language  support  takes  the  following  line: 

DB_URL  = j dbc : postgresql : //127 . 0 . 0 . l/hsphere?charSet=WIN 


Moving  PostgreSQL 

The  process  of  moving  PostgreSQL  is  similar  to  MySQL  (on  page  202),  except  for 
PostgreSQL-specific  details. 

Data  location:  ~postgres/data  for  Linux,  ~pgsql/data  for  FreeBSD. 

PhpPgAdmin  config.inc.php  server  parameter  (Step  6,  task  2): 
$conf[’servers’][$i][’host’]. 

There  is  no  need  to  perform  task  3 in  Step  5 since  mail  servers  do  not  use  PostgreSQL 
databases. 


Configuring  Parallels  H-Sphere  to  Use 
Non-Default  MySQL/PostgreSQL  Versions 
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You  can  use  versions  of  MySQL/PostgreSQL  other  than  those  included  into  Parallels 
H-Sphere  updater.  For  instance,  when  updating  to  Parallels  Pi-Sphere  3.0  with  MySQL 
5.0.x  and  Postgres  7.4.x  there  may  be  a necessity  to  use  MySQL  4.1  .x  included  into 
Parallels  H-Sphere  2.5.0  or  Postgres  8.0.x  enabled  for  a certain  operational  system.  In 
such  a situation  Parallels  Pi-Sphere  updater  allows  excluding  default  versions  of 
MySQL/PostgreSQL,  as  well  as  updating  and  configuring  them  by  means  of  native 
system  package  managers. 

> To  make  sure  CP  properly  works  with  such  custom  MySQL/PostgreSQL 
versions: 

1.  Exclude  MySQL/PostgreSQL  from  Parallels  H-Sphere  3.0+  updater 

To  exclude  the  above  mentioned  packages,  run  one  of  the  following  updater 
commands: 

exclude-mysql=show | add | del 
exclude -postgresql=show | add | del 

If  custom  MySQL/PostgreSQL  has  to  be  set  not  for  all  MySQL/PostgreSQI  logical 
servers,  set  a list  of  specific  IPs.  To  do  this,  refer  to  the  section  on  Parallels  H- 
Sphere  Update  Package  of  the  Update  Guide. 

2.  Configure  MySQL/PostgreSQL  to  support  non-default 
MySQL/PostgreSQL  versions 

> To  add  an  Parallels  H-Sphere  configuration  to  MySQL  and  PostgreSQI 
services: 

For  MySQL: 

1.  Create  -mysql/. my. cnf  file  which  contains: 

cat  -'-mysql/ .my . cnf 
[ client ] 
user=root 
pas s wo rd=PAS SWORD 

2.  Set  necessary  file  permissions: 

chmod  0400  ~mysql/ .my . cnf 
chown  mysql : mysql  ~my sql/ . my . cnf 

3.  Configure  /etc/my . cnf  file  (if  any)  according  to  your  needs 

For  PostgreSQL: 

1.  Create  pgsql  (FreeBSD)  or  postgres  (Linux)  database  user, 
hereafter  pguser 

2.  If  you  customize  CP  PostgreSQL,  create  wwwuser,  i.e.  Parallels  H- 
Sphere  main  PostgreSQL  database  user 

3.  According  to  PGDATADIR  variable  (from  startup  file),  create: 

$PGDATADIR  /global/pg_j>s 
and  add  a string  in  the  following  format: 

user  password 

4.  Set  permissions: 
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chown  $PGUSER : $PGUSER  $PGDATADIR  /global/pg_ps 
chmod  600  $PGDATADIR  /global/pg_ps 

5.  Configure  ~$pgdatadir/ pg_hba . conf  by  setting  the  list  of  subnets 
and  providing  password  type  for  validation 

6.  If  you  customize  a CP  PostgreSQL,  make  sure  you  have  correctly  set  a 
wwwuser  access  password  to  a database.  You  can  check  in  the 

~cpanel / shi va/psof  t_conf  ig/h sphere  .properties  file 

7.  Provide  a PostgreSQL  logs  rotation  according  to  syslog  facility  specified 

in  pgdatadir/ postgresql  .conf  configuration  file. 

Note:  to  check  that  MySQL/PgSQL  is  properly  configured,  run  the  following  script: 

/hsphere/pkg/ scripts /uprocedure/dbs_check 


Choosing  Remote  Web  Logical  Servers 
for  phpMyAdmin/phpPgAdmin  Frontends 

Parallels  H-Sphere  logical  web  server  is  by  default  installed  on  a physical  box  together 
with  PostgreSQL/MySQL  logical  servers,  thus  phpMyAdmin  and  phpPgAdmin 
frontends  use  Apache  on  the  same  server. 

It  is  possible  to  choose  an  alternative  remote  Web  logical  server  for  phpMyAdmin  and 
phpPgAdmin.  Now  you  can  configure  one  phpMyAdmin/phpPgAdmin  frontend  to 
manage  multiple  database  servers. 

> To  choose  remote  Web  servers  for  phpMyAdmin: 

1.  Login  as  cpanel  user  (on  page  53)  and  set  the  following  property  in 

~cpanel / shi va/psof t_conf ig/hsphere .properties: 

EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  41)  to  apply  changes. 

Important:  If  external_service_usage  is  not  set  or  is  not  TRUE,  you  will  not 
be  able  to  choose  an  external  Web  server  for  phpMyAdmin! 

2.  In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  MySQL  logical  server,  and  Choose  Unix  Hosting  server  for 
phpMyAdmin  under  Additional  Options. 

3.  Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 
hspackages  reconfig=frontend 

Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 

4.  To  move  phpMyAdmin  content  to  respective  remote  Web  logical  server 
location,  run  the  following  script  on  the  source  box: 

/hsphere/pkg/ scripts/uprocedures/dbs_content  -h 

Usage:  dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 
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dbtype:  horde  or  spamassassin  or  phpmyadmin 

ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the 
corresponding  mail  logical  server. 

password:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding 
mail  logical  server. 

> To  choose  remote  Web  servers  for  phpPgAdmin: 

1.  Login  as  cpanel  user  (on  page  53)  and  set  the  following  property  in 

~cpanel / shi va/psof t_conf ig/h sphere .properties: 
EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  41)  to  apply  changes. 

Important:  If  external_service_usage  is  not  set  or  is  not  TRUE,  you  won’t  be 
able  to  choose  an  external  Web  server  for  phpPgAdmin! 

2.  In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  PostgreSQL  logical  server,  and  Choose  Unix  Hosting  server  for 
phpPgAdmin  under  Additional  Options. 

Note:  For  security  reasons,  it  is  not  possible  to  choose  Web  logical  server  on  the 
CP  box  for  phpPgAdmin. 

3.  Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 
hspackages  reconfig=frontend 

Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 


Downgrading  Postgres 

Parallels  H-Sphere  CP  (Control  Panel)  works  correctly  only  with  Postgres  7.x.  Thus,  if 
you  have  accidentally  upgraded  Postgres  package  on  your  CP  server  to  version  8.x 
and  higher,  you  need  to  perform  its  downgrade  to  the  version  you  had. 

> To  downgrade  Postgres: 

1.  Log  into  the  control  panel  server  as  root. 

2.  Back  up  CP  postgres  home  dir. 

3.  Back  up  the  file  /etc/init . d/postgresql. 

4.  Stop  the  control  panel,  (on  page  41) 

5.  Stop  Postgres: 

/etc/rc.d/init.d/postgresql  stop 

6.  Check  what  postgres  packages  are  installed: 

rpm  -qa  | grep  -i  postgres 

7.  Uninstall  postgres: 
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rpm  -e— nodeps  'rpm  -qa | grep  -i  postgres ' 

8.  Install  an  earlier  version  of  postgres  packages.  The  installations  are 
available  on  your  CP  server  in  the  directory 

/hsphere/  install/p  kg/  <CP_OS>/ 

9.  Start  Postgres: 

/ etc/ rc . d/ init . d/postgresql  start 
10. Start  the  control  panel,  (on  page  41) 
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Windows  Servers 

This  chapter  is  dedicated  to  Parallels  H-Sphere  Windows  hosting  server  configuration. 
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MSI  Packages 

Parallels  H-Sphere  Winbox  installation  and  update  is  performed  from  MSI  packages 
each  responsible  for  a particular  functionality: 

■ HsCore  - core  of  Parallels  H-Sphere  Winbox  service 

■ Hsinstaiier  - Parallels  H-Sphere  Winbox  installer 

■ Hs  General  Ho  sting  - provides  FTP  hosting  services 

■ hsmssqL  - Parallels  H-Sphere  MSSQL  hosting  server  (requires  MSSQL  server 
installed  on  the  box) 

■ HsRSync  - RSync  utitity 

■ HsWeb  - provides  Parallels  H-Sphere  Web  resources  for  Windows  hosting 

■ HsAspNetSqiEMan  - supports  ASP.NET  Enterprise  manager 

■ HsSharePoint  - SharePoint  hosting  (requires  SharePoint  installed) 

■ HsCoidFusion  - ColdFusion  hosting  (requires  ColdFusion  installed) 

■ HsWebalizer  - Webalizer 

■ HsUrchin  - integrates  the  Google  Analytics  tool  (requires  Urchin  installed) 

■ HsMiva  - integrates  Miva  tool  (requires  Miva  installed) 

■ HsPerl  - Perl 

■ HsAWStats  - AWStatS 

■ HsStats  - Winbox  statistics  resource 

■ hsphp  - PHP  hosting,  includes  both  PHP  4 and  5 version 

■ HsWebSheii  - WebShell  Web  File  Manager 

■ HsOsCommerce  - OsCommerce 

■ HsPhpBB  - PhpBB 

■ HsEasyAppSvc  - provides  EasyApp  service  to  enable  installation  of  EasyApp 
collection 

Each  package  filename  has  the  following  notation: 

<PACKAGE_TITLE>_<HS_VERSION>.<BUILD>.<TIMESTAMP>.ms\ 

where: 

■ <PACKAGE_TITLE>  is  the  name  of  the  package  (see  the  list  above) 

■ <HS_VERSION>  is  Parallels  H-Sphere  version 

■ <BUILD>  is  the  package  build 

■ <TIMESTAMP>  is  the  package  build  timestamp  (days  from  1 Jan  2000) 

Example:  Hs  General  Ho  sting  3. 2. 152. 3195. msi. 


In  this  section: 
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Packages  Requiring  Third-party  Software 219 
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Download  and  Installation 

Parallels  H-Sphere  MSI  packages  are  downloaded  from  the 
http://download.hsphere.parallels.com/shiv/HS/WINDOWS/  location. 

There  can  be  several  cases  of  installing  these  packages: 

■ Automatic 

The  first  step  is  downloading  and  running  the  HsCore  package.  Installation/update 
of  the  rest  of  the  packages  is  managed  from  the  admin  CP  by  means  of  the  Update 
Wizard.  The  wizard  runs  them  from  the 

<HS_HOME>\data\services\installer  folder,  where  <HS_HOME>  is 
Parallels  H-Sphere  home  location  (C:\Program  Files\HSphere  by 
default ) 

In  case  of  upgrade  from  H-Sphere  2. 5/3.0: 

1 . Older  H-Sphere  home  folder  will  be  forcefully  moved  to  C:\Program 
Files\HSphere. 

2.  Older  PHP  packages  will  be  replaced  by  HsPHP. 

3.  Older  EasyApp  collection  will  be  built  into  a separate  MSI  package  and  installed 
into  the  H-Sphere  Winbox  framework. 

■ Istallation  of  the  Bundles 

Download  and  run  the  Windows  server  installation  bundles  in  accordance  with  the 
hosting  type: 

■ Windows  Web  hosting:  HS_WinHosting_Bundle<HS_VE/?S/OW>  . exe 

■ MS  SQL  hosting:  hs_mssql _Bundle  <HS_VERSION> . exe 

■ Windows  Web  + MS  SQL  hosting: 

HS  WinHosting  MSSQL  Bundle  <HS_VERSION> . exe 

■ Manual 

Not  recommended!  You  can  also  manually  install/update  Parallels  H-Sphere  Winbox 
by  downloading  these  packages  and  running  them  one  by  one,  according  to  their 
dependencies. 


Packages  Requiring  Third-party  Software 

HsMSSQL,  HsSharePoint,  HsColdFusion,  HsUrchin  and  HsMiva  integrate  third- 
party  products  into  Parallels  H-Sphere  environment  and  require  respective  software 
installed.  Please  refer  to  separate  documents  for  specific  guidelines  on  their 
configuring: 

■ SharePoint  (on  page  227) 

■ ColdFusion  (on  page  236) 

■ Miva  (on  page  351) 

■ Urchin  (on  page  355) 
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Dependencies  Tree 

Parallels  H-Sphere  Update  Wizard  installs  the  packages  in  the  following  sequence: 


Winbox  Directory  Structure 

Parallels  H-Sphere  Winbox  installation  creates  three  major  directories: 

■ HSphere 

■ HShome 

■ HSIogfiles 


In  this  section: 

HSphere 221 

HShome 221 

HSIogfiles 222 
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HSphere 

HSphere  directory  (typically  created  in  C:\Program  Files\)  includes  the  following 
directories: 

■ 3rdparty  - Third  party  software  which  is  used  by  Parallels  H-Sphere; 

■ bin  - Parallels  H-Sphere  binary  files; 

■ logs  - Parallels  H-Sphere  log  files; 

■ Config  - Parallels  H-Sphere  configuration  file  (hsphere.config); 

■ data  - Various  data  which  is  created  by  H-Sphere  components. 


HShome 

The  location  of  home  directory  depends  on  the  type  of  Winbox  installation: 

■ fresh  installation  - Winbox  directory  is  installed  to  the  path  specified  in  a 
corresponding  Physical  server  profile.  If  it  is  not  set  there,  Parallels  H-Sphere 
Winbox  installer  will  automatically  create  it  on  NTFS  partition  with  the  largest  free 
space. 

■ manual  installation  - Winbox  directory  is  created  at  the  location  you  specify  in  a 
manual  installation. 

HShome  directory  contains  all  user  homes.  Each  home  directory  has  account  owner’s 
name.  A typical  user  home  has  the  following  directories: 

logs 

domainl . com 
domain2 . com 

domainN . com 

Each  domain  directory  has  content  similar  to  the  following: 

cgi-bin 

dirl 

dir2 

dirN 

logs  directory  would  have  subdirectories  for  each  domain: 

domainl . com  - (log  files  in  exYYMMDDHH.log  W3SVC  format) 

domain2  . com  - (-//-) 


domainN . com  - (-//-) 

Note  that  cgi-bin  is  not  a required  directory  in  the  site  structure  and  depends  on 
whether  the  cgi  directory  resource  is  enabled  for  the  site.  The  same  is  true  of  log  files 
for  individual  sites,  since  Parallels  H-Sphere  has  the  transfer  log  resource  that  allows 
users  to  access  log  files  for  their  site(s). 
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HSIogfiles 

HSiogf  iles  directory  includes  HTTP  and  FTP  logs  for  all  users.  It  is  a common 
directory  which  is  located  aside  from  log  directories  in  user  homes.  You  can  set  a 
location  of  this  directory  during  the  Parallels  H-Sphere  Winbox  installation.  Typically,  it 
is  located  in  the  disk  root  directory  (<drive>:  \hsiogfiies)  and  has  the  following 
content  structure: 

hslogf iles 

I 

I—  W3SVC1  - (log  files  for  1 site  in  exYYMMDDHH.log  W3SVC  format) 

I—  W3SVC2  - (-//-) 

I—  W3SVCn  - (-//-) 

I 

I—  MSFTPSVC1  - (log  files  for  1 site  in  exYYMMDDHH.log  W3SVC  format) 

I—  MSFTPSVC2  - (-//-) 

I—  MSFTPSVCn  - (-//-) 


Restarting  Winbox  Service 

To  stop  Parallels  H-Sphere  service  on  an  Parallels  H-Sphere  Windows  server,  run  in 
command  prompt: 

net  stop  HSphere 
net  stop  HsQuotas 

To  start  Parallels  H-Sphere  service  on  a Winbox,  run: 

net  start  HSphere 
net  start  HsQuotas 
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Restarting  IIS 

To  restart  IIS  on  an  Parallels  H-Sphere  Windows  server,  run  in  command  prompt: 

iisreset  /stop 
iisreset  /start 

Or,  simply: 

iisreset  /restart 


Enabling  Winbox  Shared  SSL 

Starting  with  WINDOWS  2003  SP1 , IIS  6.0  supports  host  headers  in  SSL  bindings 
(http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/596b91 

08-bl  a7-494d-885d-f8941  b07554c.mspx?mfr=true). 

Requirements:  Windows  2003  with  SP1  or  Windows  2000  server;  Parallels  H-Sphere 
3.0  Final 

This  document  covers  Winbox  Shared  SSL  integration  and  update. 


In  this  section: 
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Updating  Winbox  Shared  SSL 224 


Integrating  Winbox  Shared  SSL 

IIS  6.0 

Shared  SSL  service  virtual  hosts  are  not  used  anymore. 

Admin  shared  SSL  creation: 

■ Post  certificate  and  key  to  the  server.  The  name  of  key  container  is  {3716B9D2- 
2 4 8 6 - 4 4 6 a - 9 2 8 1 - e 4 d l c a 0 3 e c 0 a } _<  wild-card  domain  name> 

User  shared  SSL  creation: 

■ Enable  SSL  with  appropriate  shared  SSL  certificate  for  customer’s  virtual  host 

■ Set  the  SecureBindings?  of  customer’s  virtual  host  to  <IP> : 4 4 3 : <domain  alias> 
where  domain  alias  is  3rd  level  domain  alias  for  customer  shared  SSL. 
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Updating  Winbox  Shared  SSL 

If  there  is  shared  SSL  hosting  on  the  server  managed,  the  upgrade  procedure 
automatically  migrates  shared  SSL  to  a new  scheme.  It  detects  shared  SSL  by 
existence  of  virtual  hosts  with  Parallels  H-Sphere  shared  SSL  Log  plugin  log  plugin  and 
by  HKLM\ SOFTWARE \ Pso ft \HSphe re \SharedSSL \ Virtual  registry  key 
existence.  Before  performing  migration,  it  makes  IIS  metabase  backup  called 
sharedSSL  used  to  restore  metabase  if  something  goes  wrong.  Migration  procedure 
makes  the  following  changes: 

IIS  6.0 

Shared  SSL  service  virtual  hosts  are  removed. 

User  host: 

■ enables  SSL  with  appropriate  wild-card  certificate  for  customer’s  virtual  host 

■ sets  secure  binding  to  <IP> : 443 : <domain  alias>  where  “domain  alias”  is  3rd  level 
domain  alias  for  customer  shared  SSL 
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Winbox  Statistics 


Parallels  H-Sphere  Winbox  has  the  following  log  plugins  installed: 

1.  Parallels  H-Sphere  Web  Log  plugin:  a standard  log  plugin  for  virtual 
host  designed  to  calculate  statistics  info  only.  Besides,  for  a particular 
site  it  generates  HTTP  log  files  similar  to  W3C  log  format  files  in  the 
site’s  log  directory. 

2.  Parallels  H-Sphere  Web  Transfer  Log  plugin:  can  work  instead  of  the 
Web  Log  plugin.  It  also  implements  the  transfer  log  and  AWStats  log 
generating  functionality  beyond  the  standard  behavior. 

3.  Parallels  H-Sphere  Shared  SSL  Log  plugin:  used  only  on  shared  SSL 
sites. 

4.  Parallels  H-Sphere  Guest  FTP  Log  plugin:  installed  on  the  default 
FTP  host  to  collect  FTP  statistics  on  account  basis. 

5.  Parallels  H-Sphere  FTP  Log  plugin:  installed  on  each  anonymous 
FTP  site  to  collect  FTP  statistics  on  FTP  site  basis. 

Please  mind  the  restrictions  common  to  all  Parallels  H-Sphere  log  plugins: 

1.  All  log  files  are  rotated  daily  and  there  is  no  way  to  change  this  rotation 
period. 

2.  Log  format  settings  can’t  be  changed  for  Parallels  H-Sphere  log 
plugins. 


In  this  section: 


Statistics  Modules 
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Statistics  Modules 

Services.Stats.dll 

Location: 

. . . \HSphere\bin\services\Services . Stats . d 
11 


H-Sphere  invokes  Service. Stats. dll  daily  at  00:01  AM.  However,  if  HSphere.exe  is 
restarted  between  00:00  AM  and  06:00  AM,  Service.Stats.dll  will  start  together  with 
Parallels  H-Sphere. exe;  the  next  day  Service.Stats.dll  will  run  at  00:01  as  usual. 

When  invoked  Service.Stats.dll  performs  the  following: 

1.  Rotates  logs  (W3SVC,  W3FTP)  in  . . . \hslogf iies\,  analyzes  every 
log  file  and,  if  a log  was  created  more  than  a month  ago,  moves  that  file 
to  the  archive  of  log  files  for  that  month.  Archives  are  never  rotated; 

2.  Collects  Webalizer  statistics; 

3.  Collects  AWstats  statistics; 

4.  Cleanses  log  files  in  the  users  homes; 

5.  Executes  wawrapper.exe  and  awstats_updateall.pl; 

Rotates  the  user’s  log  files  in  the  ...\home\<account_name>\log\<domain_name> 
directories.  All  log  files  created  more  then  a week  ago  will  be  deleted. 

WaWrapper.exe 

Location:  . . .\HSphere\bin\wawrapper.exe. 

WaWrapper.exe  analyzes  the  webalizer . current  files  for  each  domain. 

If  the  webalizer . current  file  is  not  corrupted,  WaWrapper.exe  creates  a backup 
copy  of  it  in  the  . . . \HSphere\wawrapper  directory  and  names  it  by  the  name  of  the 
domain  where  the  webalizer . current  resides. 

If  the  webalizer . current  file  is  corrupted,  wawrapper.exe  deletes  it  and  restores 
the  backup  copy  from  . . . \HSphere\wawrapper  directory. 

Then,  it  copies  the  files  hostslist.txt,  webalizer . conf , Webalizer  .exe  to  the 
temp  directory  and  executes  Weba\izer.exe  for  each  group  of  records  from  the 

hostslist . txt  file. 

Webalizer  is  a third-party  product  installed  apart  of  Parallels  H-Sphere.  Its  target 
location  is  specified  by  customer  during  installation. 

The  number  of  records  in  each  group  is  set  by  default  to  l.  You  can  change  this  value 
by  adding  the  HostsinPackage  parameter  to  the  registry  key 

HKE Y_LOCAL_MACHINE\ SOFTWARE \Psoft\HSphe re \WaWrapper.  The 
HostsinPackage  value  is  unsigned  integer. 

Wawrapper.exe  monitors  Webalizer’s  read/write  operations.  If  a period  between 
read/write  operations  is  greater  than  timeout , WaWrapper  kills  this  webalizer  process 
and  all  records  in  this  group  adds  to  the  . . . \webaiizer\errhostsiist . txt  file. 
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The  default  timeout  is  60  seconds.  You  can  change  this  value  by  adding  the  Timeout 
parameter  to  the  registry  key 

HKE Y_LOCAL_MACH INE\ SOFTWARE \Psoft\HSphe re \WaWrapper.  The  Timeout 
value  is  unsigned  integer,  in  seconds. 

If  Webalizer.exe  returns  an  error  code  other  than  0,  all  records  in  a group  will  be  added 

to  errhostslist.txt. 

Important:  With  lots  of  statistics,  it  may  take  up  to  several  days  or  even  weeks  for 
Webalizer.exe  to  process  it.  In  such  cases,  some  of  the  statistics  may  be  lost. 


Awstats_updateall.pl 

Location:  . . . \HSphere\3rdparty\AWStats\tools\awstats_updateall  .pi 

awstats_updateall.pl  is  an  AWStats  tool  for  automatic  statistics  processing  on  all 
domains  for  which  the  AWStats  resource  is  turned  on  in  CP.  AWStats  automatically 
rotates  the  processed  records  to  the  awstats . log  files  in  domain  log  directories. 

Module  Log  Files 

Services.StatS.dll:  . . . \HSphere\log\services\stats\*.* 

WaWrapper.exe:  . . . \HSphere\logs\wawrapper\* . * 

AwstatS_updateall.pl:  . . .\HSphere\3rdparty\AWStats\common.log 


Setting  Up  SharePoint  to  Use  MSSQL 
Server 


This  document  gives  you  information  on  how  to  install  Microsoft  Windows  SharePoint 
Services  on  your  Windows  2003  web  servers. 

According  to  Microsoft 

(http://www.microsoft.com/windowsserver2003/technologies/sharepoint/default.mspx), 

Windows  SharePoint  Services  technology  “is  an  integrated  portfolio  of  collaboration 
and  communication  services  designed  to  connect  people,  information,  processes,  and 
systems  both  within  and  beyond  the  organizational  firewall.  SharePoint  sites  provide  a 
central  repository  for  documents,  information,  and  ideas,  and  enable  users  to  work 
interactively  with  these  items.” 

Currently  we  support  Windows  SharePoint  Services  v2  with  Service  Pack  2, 
http://www.microsoft.com/downloads/details.aspx?FamilylD=3144b72b-b4f2-46da- 

b4b6-c5d7485f2b42&DisplavLanq=en. 

In  this  section: 
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Installing  and  Configuring  SharePoint 228 


228 


Windows  Servers 


Preinstallation  Requirements 

Before  you  install  Microsoft  Windows  SharePoint  Services  on  your  Web  server,  make 
sure  that  you  have  installed  the  required  hardware  and  software. 


Required 

Details 

Important:  SharedPoint  and  MSSQL  should  be  installed  on  one  and  same 
physical  server. 

Server  Hardware 

* Intel  Pentium  III  (and  later)  compatible 
processor 

* CPU/550  MHZ  1 CPU  (2  recommended) 

* 512  MB  RAM 

Operation  System 

Microsoft  Windows  Server  2003: 

■ Standard  Edition 

■ Enterprise  Edition 

■ Datacenter  Edition 

Server  Software 
(Web  application 
server) 

■ NTFS  file  system 

■ Microsoft  ASP.NET 

■ Internet  Information  Services  in  IIS  6.0  worker  process 
isolation  mode  with  the  SMTP  service 

Server  Databases* 

* Microsoft  SQL  Server  2000  Service  Pack  3 or  later 
■ Microsoft  SQL  Server  2005 

Browser  Client 

■ Microsoft  Internet  Explorer  5.01  or  later 

■ Microsoft  Internet  Explorer  5.5  or  later 

■ Netscape  Navigator  version  6.2  or  later 

■ Mozilla  1.4  or  later 

• Microsoft  Windows  SharePoint  Services  SQL  Server  2000  Desktop  Engine 
(WMSDE)  is  not  supported  by  Parallels  H-Sphere. 


Installing  and  Configuring  SharePoint 

To  install  and  configure  SharePoint  Services,  follow  the  procedure  below. 


In  this  section: 


Step  1.  Installing  MSSQL  Server 229 

Step  2.  Selecting  Authentication  Mode  for  SQL  Server 230 

Step  3.  Installing  SharePoint 231 

Step  4.  Configure  Parallels  H-Sphere  to  Use  SharePoint 231 
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Step  1.  Installing  MSSQL  Server 

Prior  to  installing  SharePoint,  you  need  to  install  MSSQL  Server.  You  can  chose 
between: 

■ MSSQL  Server  2000 

■ MSSQL  Server  2005  (on  page  251) 
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Step  2.  Selecting  Authentication  Mode  for  SQL  Server 

In  order  to  allow  Windows  SharePoint  Services  to  connect  to  your  SQL  Server 
database,  it  is  recommended  that  you  configure  the  SQL  Server  database  to  use 
Windows  authentication. 

For  SQL  Server  2000: 

1.  On  your  server  computer,  go  to  Start  ->  All  Programs  ->  Microsoft  SQL 
Server  ->  Enterprise  Manager. 

2.  In  Enterprise  Manager,  click  the  plus  sign  (+)  next  to  Microsoft  SQL 
Servers. 

3.  Click  the  plus  sign  (+)  next  to  the  SQL  ServerGroup. 

4.  Right-click  the  SQL  Server  name,  and  go  to  Properties. 

5.  In  the  Properties  dialog  box,  click  the  Security  tab. 

6.  In  the  Authentication  section: 

■ If  you  want  use  the  MSSQL  Server  only  for  Microsoft  Windows  SharePoint 
Services,  select  only  Windows  Authentication  mode. 

■ If  you  want  use  the  MSSQL  Server  both  for  Microsoft  Windows  SharePoint 
Services  and  hosting,  select  SQL  Server  and  Windows  Authentication 

mode. 

7.  Click  OK. 


Note:  If  you  have  used  a domain  account  that  does  not  already  have  database  creation 
rights  in  SQL  Server,  you  can  give  the  account  this  access  using  Enterprise  Manager  in 
SQL  Server  2000,  as  a temporary  solution. 


For  SQL  Server  2005: 

1.  On  your  server  computer,  go  to  Start  ->  All  Programs  ->  Microsoft  SQL 
Server  2005  ->  SQL  Server  Management  Studio. 

2.  On  the  Connect  to  Server  screen,  select  the  name  of  the  local  server 
from  the  Server  name  drop-down  list. 

3.  On  the  Server  Properties  - Server  name  screen,  click  Security  in  the 
Select  a page  section. 

4.  In  the  Server  Authentication  section: 

■ If  you  want  use  the  MSSQL  Server  only  for  Microsoft  Windows  SharePoint 
Services,  select  only  Windows  Authentication  mode. 

■ If  you  want  use  the  MSSQL  Server  both  for  Microsoft  Windows  SharePoint 
Services  and  hosting,  select  SQL  Server  and  Windows  Authentication 

mode. 

5.  Click  OK. 

Note:  If  you  have  used  a domain  account  that  does  not  already  have  database  creation 
rights  in  SQL  Server,  you  can  give  the  account  this  access  using  SQL  Server 
Management  Studio,  as  a temporary  solution. 
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Step  3.  Installing  SharePoint 

By  default,  when  you  install  Windows  SharePoint  Services,  the  Setup  program  installs 
WMSDE  (Microsoft  Windows  SharePoint  Services  SQL  Server  Desktop  Engine). 
Parallels  H-Sphere  does  not  support  WMSDE.  To  use  SharePoint  with  SQL  Server, 
run  Setup  with  the  Server  Farm  option.  Server  Farm  option  allows  supporting  a 
larger  set  of  Web  sites. 

1.  Download  and  install  SharePoint: 
http://www.microsoft.com/windowsserver2003/technoloqies/sharepoint/ 

default.mspx 

WARNING:  During  SharePoint  setup,  you  may  get  the  error  when  connecting  to 
http://localhost:SharePointPort/.  To  solve  it,  you  should  remove  the  string  cidentity 

impersonate=”true”  />  from  C:\Program  Files\Common  Files\Microsof t 
Shared\Web  Server 

Extensions  \ 60  \template\admin\  1033  \web  . con  fig.  Also  please  check  the 
Authentication  Methods  for  SharePoint  Central  Administration  WebSite  in  IIS.  And  if 
Basic  authentication  is  disabled,  enable  it. 

2.  Go  to  SharePoint  Central  Administration: 

Start /Settings /Control  Panel/ Administrative 
Tools /SharePoint  Central  Administration 

3.  Configure  Administrative  Virtual  Server  in  the  Server  Configuration  tab: 

■ Select  Use  an  existing  application  pool  and  chose  StsAdminAppPool 

■ Go  to  Security  Configuration  and  select  NTLM 

■ Click  OK 

4.  Configure  Database  Server  in  the  Server  Configuration  tab: 

■ Select  Database  Server  and  enter  your  MSSQL  Server  IP  or  MSSQL  instance 

■ In  SQL  Server  database  name  enter  your  SharePoint  Main  DB  NAME 

■ Set  Windows  authentication 

5.  In  Active  Directory  Account  Creation  choose  Users  already  have 
domain  accounts.  Do  not  create  active  directory  accounts. 

6.  Click  OK 

Step  4.  Configure  Parallels  H-Sphere  to  Use  SharePoint 

1.  If  you  installed  Microsoft  Windows  SharePoint  Services  after  Parallels 
H-Sphere  is  updated,  run  the  Parallels  H-Sphere  updater  again. 

2.  Open  HSphere  . config  file  located  in  the  { disk  } \Program 
Files\HSphere\Config\  directory  and  make  sure  the  correct  name 
of  your  MSSQL  server  was  set  in  the  SharePoint  resource  setting 
during  Parallels  H-Sphere  update. 

3.  Restart  Parallels  H-Sphere  service: 

net  stop  hsphere 
net  start  hsphere 
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Adding  ODBC  Resource 

This  document  explains  how  to  add  your  own  ODBC  drivers  to  Parallels  H-Sphere 
Winbox.  Please  contact  us  if  this  document  doesn’t  work  for  your  version  of  Parallels 
H-Sphere. 


In  this  section: 


Interface 232 
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Interface 

The  following  scripts  are  used: 

■ odbc-getdrivers . asp 

■ odbc-getparams . asp 

■ odbc-createdatasrc . asp 

■ odbc-updatedatasrc . asp 

■ odbc-deletedatasrc . asp 

In  this  section: 


odbc-getdrivers. asp 232 

odbc-getparams. asp 233 

odbc-createdatasrc.asp 233 

odbc-updatedatasrc.asp 234 

odbc-deletedatasrc.asp 234 


odbc-getdrivers.asp 

description:  returns  a list  of  available  ODBC  divers 

parameters: 

none 

return  value: 

successful  - 0<list  of  driver  names> 
fail  - error  message 

comments: 

script  returns  the  list  of  drivers  that  are  both  installed  on  the  box  and  supported  by 
Parallels  H-Sphere  2.x  (they  are  registered  in  ODBCIniFile). 
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odbc-getparams.asp 

description: 

returns  a list  of  addmissible  attributes  for  this  ODBC  driver 
both  methods  “GET”  and  “POST”  are  supported 

parameters: 
driver  - driver  name 

return  value: 

successful  - 0 <list  of  admissible  driver  attributes> 
fail  - error  message 

comments: 

every  parameter  has  the  following  format: 

<attribute  name>  | <type>  \ <default 

value>  | <description>  | [<valuel  [ ;value2  [ ;value3 . . . ] 

See  below  for  details  on  this  format. 

odbc-createdatasrc.asp 

description: 

creates  new  data  source 
only  “POST”  method  is  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source 
user-name  - user’s  accout  name 

<list  of  admissible  attributes  of  this  ODBC  driver  and  their  values> 

return  value: 

successful  - 0 

fail  - error  message 

comments: 

1 ) all  attributes  with  empty  values  are  ignored; 

2)  all  attributes  with  a type  path  (see  below)  get  a path  to  user’s  homedir,  but  the 
existence  of  this  path  is  not  verified 

3)  data  source  name  is  created  according  to  the  pattern:  user-name  + DSN 
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odbc-updatedatasrc.asp 

description: 

updates  parameters  of  the  existing  data  source 
only  “POST”  method  is  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source 
user-name  - user’s  accout  name 

<list  of  admissible  attributes  of  this  ODBC  driver  and  their  values> 

return  value: 

successful  - 0 

fail  - error  message 

comments: 

default  values  are  set  for  attributes  that  have  not  been  specified  or  have  empty  values, 
all  comments  to  data  source  creation  are  also  true  of  data  source  update. 

odbc-deletedatasrc.asp 

description: 

deletes  existing  data  source. 

both  “GET”  and  “POST”  methods  are  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source. 

user-name  - user’s  accout  name 

return  value: 

successful  - 0 

fail  - error  message 

comments: 

no  comments 
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Configuration 

To  configure  ODBC  use  a file  of  the  below  format.  Full  path  to  this  file  is  registered  in 
conf.inc  (the  “ODBCIniFile”  variable).  By  default  it  is  called  “odbcdrv.ini”  and  sits  in  the 
directory  with  ASP  scripts. 

This  file  has  a usual  windows  .ini  file  format,  i.e.  is  broken  into  sections  with  headings 
enclosed  in  square  brackets.  Every  section  corresponds  to  an  ODBC  driver,  its  name 
being  the  heading  of  the  section.  The  body  of  the  section  includes  driver  attributes  in 
the  following  format: 

<attribute  name>=<type>  l<default  value>l<description>l[<value1  [;vatue2[;value3. . .] 
where: 

■ <attribute  name>  - name  of  the  ODBC  driver  attribute  (e.g.  DBC) 

■ <type>  - typically  a string  of  the  type:  <typeid>_[required|optinal],  where  typeid  is 
the  name  of  the  type,  e.g.  “string”,  that  can  be  required  or  optional  depending  on 
the  parameter.  Can  take  the  following  values: 

path_required  - required  path  (an  individual  path  type  is  required  to  identify 

relative  path  to  userhome  dir) 

path_optionai  - optional  path 

string  required  - required  string 

string_optionai  - optional  string 

string_password  - password 

integer_required  - mandatory  integer  value 

integer_optionai  - optional  integer  value 

seiect_required  - mandatory  list  of  values 

seiect_optionai  - optional  list  of  values 

trigger  - radio-button  switch 

■ <default  value>  - default  value  for  the  given  attribute;  a space  if  missing  (NOT  AN 
EMPTY  STRING!) 

■ <description>  - attribute  description 

■ cvaiuel  [ ; vaiue2  [ ; vaiue3 ...  - values  for  the  list;  must  be  filled  only  for  the 
‘select’  types.  Use  semicolon  (;)  as  delimiter. 

To  add  a new  ODBC  driver  to  the  ODBCIniFile,  add  a new  section  with  the  heading 
identical  to  the  name  of  the  driver  and  the  attributes  that  are  described  according  to  the 
above  rules. 

Note:  When  a user  enables  an  ODBC  resource,  Parallels  Pi-Sphere  lists  drivers  that 
can  be  found  both  among  those  installed  on  the  server  and  those  in  the  odbcdrv.ini  file. 
The  obcdrv.ini  file  contains: 

■ [Microsoft  Paradox  Driver  (*.db  )] 

■ [Microsoft  Access  Driver  (*.mdb)] 

■ [Microsoft  Visual  FoxPro  Driver] 

■ [Microsoft  dBase  Driver  (*.dbf)] 

■ [Microsoft  Excel  Driver  (*.xls)] 

■ [SQL  Server] 

• [MySQL] 

■ [MySQL  ODBC  3.51  Driver] 
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■ [PostgreSQL] 


Configuring  ColdFusion 

ColdFusion  includes  a server  and  a development  toolset  designed  to  integrate 
databases  and  Web  pages.  With  ColdFusion  Fusion,  a user  can  enter  a zip  code  on  a 
Web  page,  and  the  server  would  query  a database  and  present  the  results  in  the  FITML 
form. 

For  extensive  coverage  of  ColdFusion,  please  refer  to 
http://www.adobe.com/downloads/. 

WARNING:  We  currently  don’t  recommend  updating  Parallels  Pi-Sphere  to  version  2.5 
and  up  when  there  are  51 2 and  more  ColdFusion  mappings  on  a Windows  server  (i.e., 
ColdFusion  is  turned  on  for  more  than  51 1 Winbox  users)! 


> To  configure  ColdFusion  for  Parallels  H-Sphere: 

1.  Buy  ColdFusion  license  package. 

2.  Install  ColdFusion  on  your  Windows  box  following  the  directions  of  the 
Wizard.  (Parallels  H-Sphere  2.5  and  up  supports  6.0,  6.1, 7.0,  and  9.0 
ColdFusion  versions). 

3.  Install  latest  Parallels  H-Sphere  Winbox  3.1  Beta  2 or  higher. 

When  performing  the  step-by-step  installation  procedure,  set  also  ColdFusion 
admin  password  via  the  interface  after  a logical  win  server  have  been  added.  To  do 
this,  Go  to  E.  Manager  ->  Servers  - > L.Servers  and  click  the  logical  win  server  name. 
Enter  the  password  in  the  Additional  options  section  and  click  Set: 

r~ 


You  may  also  install  ColdFusion  on  a ready  Parallels  H-Sphere  3.1  Beta  2 and  higher 
Winbox.  For  this,  do  the  following: 

1.  Perform  steps  1 and  2 described  above. 

2.  Enter  ColdFusion  admin  password  via  the  interface. 

3.  Run  Parallels  H-Sphere  Update  Wizard. 
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Specifying  Default  ASP.NET  Version 

When  an  ASP.NET  resource  is  enabled  in  a plan,  the  default  ASP.NET  version  is  used 
during  account  creation.  This  version  depends  on  the  Winbox’  OS: 

■ On  Windows  2003,  the  default  ASP.NET  version  is  1 .1 

■ On  Windows  2008  and  later,  the  default  ASP.NET  version  is  2.0 

Starting  with  H-Sphere  3.4.1  you  can  control  the  default  ASP.NET  version  for  Windows 
2003  boxes.  To  specify  ASP.NET  2.0  as  a default  do  the  following: 

1 . Open  the  HSphere\Conf  ig\hsphere . conf  ig  file  and  modify  the  asp_net 
resource  declaration. 

This  declaration 

Cresource  name="asp  net"  ...  /> 

you  should  modify  to: 

Cresource  name="asp  net"  ...  > 

<prop  name="def aultversion"  value="2 . 0 . 50727" 
description="Def ault  ASP.NET  version  for  new  sites."  /> 
</resource> 

2.  Restart  H-Sphere  on  the  box. 


Enabling  ASP.NET  4.0 

On  Windows  2008  x64  H-Sphere  supports  ASP.NET  4.0.  We  recommend  installing  it 
(refer  to  http://msdn.microsoft.com/en-us/library/5a4x27ek.aspx  for  instructions)  before 
the  H-Sphere.  However,  it  is  also  possible  to  install  ASP.NET  4.0  later.  In  this  case  the 
following  steps  are  needed  to  make  it  work  properly  after  the  installation: 

1 . In  machine  .config  files  residing  in 

%windir%\ Microsoft. NET\Framework\ v4 .0.30319\Config  and 
%windir%\ Microsoft. NET\Framework64 \ v4 .0.30319\Config 

the  following  changes  should  be  made: 

1 . Attribute  aiiowDef  inition="MachineOniy"  should  be  added  to  the 

Csection  name="identity"/> tag. 

2.  Cidentity  impersonate="true"  />  tag  Should  be  added  to  the 
<system.web>  section. 

2.  Ensure  that  ASP.NET  4.0  ISAPI  modules  are  added  to  the  IIS  and  are 
allowed. 

3.  Restart  Parallels  H-Sphere  Winbox  service  (on  page  222). 
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Moving  Log  Files 

This  document  explains  how  to  change  the  HSLOGFILES  directory  location  on  Winbox. 
This  may  be  required,  for  instance,  if  you  are  replacing  your  HDD. 

1.  Link  the  new  HDD  to  the  old  HSLogs  location.  This  can  be  done  with 
Sysinternals  Junction 

(http://www.svsinternals.eom/ntw2k/source/misc.shtml#iunction)  or  any 
other  utility  of  this  kind. 

2.  Copy  logs  into  the  ‘hslogf  iles’  directory  on  the  new  HDD. 

3.  Update  value  of  ‘logsdir’  property  in 

\ H Spher e \ Co nfig\h sphere . con fig. 

4.  Restart  hsphere  services. 
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Removing  Old  Log  Files 

User  log  files  are  stored  for  7 days  and  then  automatically  removed. 

> To  remove  old  log  files  manually: 

1 . Go  to  the  HSphere\Conf  ig\  directory.  In  the  h sphere  . con  fig  file 
find  the  directory  where  logs  are  stored. 

//  path  to  directory  where  logs  are  located 
logPath  = “d:\\HSIogfiles” 

1.  Go  to  the  respective  directory  (cd  d:\hslogfiles) 

Here  you  will  find  directories  containing  web  and  ftp  log  files  for  each  domain 
e.g.:  w3svci,  W3SVC2,  W3SVC3,  msftpi,  msftp2,  msftp3  and  so  on. 

2.  Enter  “del  /s  /q  <mask>”  command  in  the  command  line  where 
<mask>  is  the  mask  for  the  files  to  be  removed. 

• You  can  use  a wildcard  in  the  mask. 

Names  of  the  log  files  have  the  following  appearance: 

exyymmddhh.  log  Or  just  exyymmddhh 

where 

ex  - the  essential  part  of  the  name 
yy  - two-digit  year  value 
mm  - two-digit  month  value 
dd  - two-digit  day  value 
hh  - two-digit  hour  value 

Examples  of  how  to  use  the  del  command: 

del  /s  /q  exOi*  - removes  all  files  for  the  year  2001 

del  /s  /q  ex0i02*  - removes  all  files  for  February,  2001 

del  /s  /q  ex??02*  - removes  all  files  for  February  of  all  the  years 

? - Any  single  character 
* - Zero  or  more  characters 
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Moving  User  Homes 

This  document  explains  how  to  move  the  directory  for  user  homes  to  a different 
location.  This  may  be  required,  for  instance,  if  you  are  replacing  your  hard  drive  with  a 
bigger  one. 

Winbox  supports  only  one  directory  for  user  homes,  which  means  you  can’t  add 
another  directory  for  user  homes  to  use  alongside  with  the  one  you  already  have. 

> To  change  HSHOME  directory: 

1 . Add  new  HDD 

2.  Create  new  HSHOME  directory 

3.  Copy  all  user  content  into  the  new  HSHOME  directory  with  Xcopy.  For 
example,  to  copy  from  disk  D:  to  disk  F:,  execute  in  the  command 
prompt: 

Xcopy  d:\hshome  f:\hshome  /O/E 

4.  Change  the  path  to  HSHOME  directory  in: 

■ Registry  key 

HKEY_LOCAL_MACHINE\SOFTWARE\ Psof t\HSphere\HsGeneralHosting\ 
QuotaService\HomeDir 

■ [H-Sphere  installation] \Config\hsphere . config 

5.  Restart  all  Parallels  H-Sphere  services 

6.  Link  the  new  HDD  to  the  old  home  dir  location.  This  can  be  done  with 
Sysinternals  Junction 

(http://download.hsphere.paralleis.com/shiv/WinBox/linkmaqic.exe)  or 

any  other  utility  of  this  kind. 

7.  Move  quota  entries  for  all  accounts  using  the  QuotaMove  utility 
(http://download.hsphere.parallels.com/shiv/WinBox/QuotaMove.exe). 

For  example,  to  move  quote  entries  from  disk  D:  to  disk  F:,  execute  in 
the  command  prompt: 

QuotaMove . exe  d : \ f : \ 


Changing  hsadmin  Login  and  Password 

Parallels  H-Sphere  control  panel  accesses  Windows  boxes  with  the  hsadmin  user. 

> To  change  the  hsadmin  login  and  password: 

1.  Generate  a new  password  hash  using  the  following  tool: 

http://download.hsphere.parallels.com/shiv/WinBox/HashGenerator.zip 

In  cmd  window,  run: 

• HashGenerator.exe  "password" 
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2.  Put  the  new  hash  to  the  following  line  in  the 

\HSphere\Config\hsphere  . conf  ig  file: 

"prop  name="password"  value="new  HASH"  description="Parallels 
H-Sphere  user  password" 

3.  Restart  Parallels  H-Sphere  services  and  change  the  password  on  your 
administrator  control  panel  for  the  Windows  physical  server. 


Winbox  IP  Migration 

This  section  explains  how  to  migrate  a pool  of  IPs  on  Parallels  H-Sphere  Winbox, 
including  physical  server  IPs,  logical  server  IPs,  and  user  dedicated  IPs.  It  is  important 
that  Parallels  H-Sphere  Winbox  software  is  working  correctly  at  the  time  of  migration. 


In  this  section: 


Step  1 . Bind  Target  IPs  on  Winbox 241 

Step  2.  Add  Double  Bindings  on  IIS 242 

Step  3.  Create  Migration  XML 243 

Step  4.  Run  the  Migration 243 

Step  5.  Remove  Old  IP  Bindings  on  IIS 244 


Step  1 . Bind  Target  IPs  on  Winbox 

Make  sure  all  the  target  IPs  are  up.  If  they  aren’t  you  can  either  bind  them  manually  or 
use  the  following  steps: 

1.  Create  a file  named,  for  instance,  target_ips.txt  with  the  list  of  IPs  and 
masks  to  bind,  as  follows: 

<IP1>  <netmask> 

<IP2>  <netmask> 

<IPn>  <netmask> 

2.  Download  IpCreator  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipcreator.exe. 

3.  Run  the  IpCreator  utility: 

IpCreator.exe  target_ips.txt  > log.txt 
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Step  2.  Add  Double  Bindings  on  IIS 

On  this  step,  we  will  duplicate  IP  bindings  for  virtual  web  hosts  on  IIS  to  use  old  and 
new  IP  bindings  simultaneously,  which  will  help  us  avoid  DNS  propagation  downtime. 

1.  Create  a file  named,  for  instance,  ip_map.txt  with  space  separated  old 
and  new  IP  correspondences,  according  to  the  following  format: 


<old 

IP1> 

Cnew 

IP1> 

Cold 

IP2> 

Cnew 

IP2> 

Cold 

IPn> 

Cnew 

IPn> 

2.  Download  IpMigrator  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipmiqrator.exe. 

3.  Run  the  IpMigrator  utility: 

ipmigrator . exe  ip_map . txt  > ipmigrator . log 

Note:  IpMigrator  inserts  new  bindings  AFTER  the  corresponding  old  bindings  in  the  IIS 
metabase.  Parallels  H-Sphere  uses  the  first  binding  to  obtain  virtual  web  host  name 
and  IP,  which  means,  while  the  old  bindings  exist  in  the  bindings  list,  Parallels  H- 
Sphere  will  manage  resources  with  the  old  IP.  For  instance,  Parallels  Pi-Sphere  will  add 
host  aliases  to  the  old  IP’s.  Thus  it  is  strongly  recommended  to  remove  old  IP  bindings 
as  soon  as  they  are  not  needed. 
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Step  3.  Create  Migration  XML 

Create  file  ipmigration.xml  of  the  following  format  and  put  it  on  the  CP  server: 

<?xml  version=”1 .0”?> 
clDOCTYPE  ips  [ 

<!ELEMENT  ips  (ip+)> 

<!ELEMENT  ip  (#PCDATA)> 

<!  ATT  LI  ST  ip  name  CDATA  #REQUIRED> 

<!  ATT  LI  ST  ip  newjp  CDATA  #REQUIRED> 

<!ATTLIST  ip  new_mask  CDATA  “[New_NetMask]”> 

]> 

<ips> 

<!■■  Delete  the  lines  with  IPs  you  don’t  want  to  migrate!  ■■> 

<ip  name=”[Old_IP1]”  new_ip=”[New_IP1]”/> 

<ip  name=”[Old_IP2]”  new_ip=”[New_IP2]”/> 

<ip  name=”[Old_IP3]”  new_ip=”[New_IP3]”/> 

<ip  name=”[Old_IP4]”  new_ip=”[New_IP4]”  new_mask=”[New_NetMask2]”/> 

</ips> 

You  can  find  more  information  on  ipmigration.xml  in  Changing  IPs  for  the  Parallels  hl- 
Sphere  Cluster  (on  page  39). 


Step  4.  Run  the  Migration 

1.  Stop  Parallels  H-Sphere  (on  page  41) 

2.  Execute  the  following  commands  one  by  one  on  the  CP  server.  Replace 
<LS_ID>  with  the  ID  of  the  Winbox  logical  server.  To  find  out  the  ID  of  the 
logical  server,  go  to  E.Manager ->  L.Servers  in  Parallels  H-Sphere  admin 
panel. 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast— ip- 
change— lServerIds=<LS_/D>  ipmigration . xml 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast— 

recreate-  zone— lServer  Ids=<LS_/D>  ipmigration . xml 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . IPMigratorFast— 

service-zone— lServerIds=<LS_/D>  ipmigration  . xml 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . IPMigratorFast— 

cus tom-rec— lServerIds=<LS_/D>  ipmigration . xml 

3.  Start  Parallels  H-Sphere  (on  page  41) 
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Step  5.  Remove  Old  IP  Bindings  on  IIS 

At  this  point  in  time,  you  have  duplicate  bindings  of  new  and  old  IPs.  It  is  recommended 
that  you  remove  old  IP  bindings  as  soon  as  DNS  servers  across  the  world  refresh 
themselves  (usually  in  no  more  than  2 days). 

The  old  bindings  on  IIS  can  be  removed  with  the  IpChange  utility  (),  which  uses  the 
same  IP  map  file  as  the  IpMigrator  utility  (step  2 above). 

1.  Download  IpChange  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipchanqe.exe 

2.  Run  IpChange  utility: 

ipchange . exe  ip_map . txt  > ipchange . log 

3.  Restart  Parallels  H-Sphere  (on  page  41). 


Winbox  Security  Scheme 

Parallels  H-Sphere  introduces  a Winbox  security  scheme.  The  goal  of  the  scheme  is  to 
get  rid  of  'local  system'  identity  for  application  pool  processes  of  IIS  6.0,  to 
simplify  some  tasks  such  as  managing  FrontPage  and  ASP.NET,  and  to  make 
Parallels  Pi-Sphere  accounts  hierarchy  more  structural. 


In  this  section: 

Accounts  Plierarchy 245 

IIS  Security  Management 246 

NTFS  permissions 247 

FrontPage  Server  Extensions  Management  Notes 247 

ASP.NET  Management  Notes 248 

Migration  Notes 248 

Recovery  Notes 248 
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Accounts  Hierarchy 

Features: 

■ There  are  several  predefined  security  groups: 

■ hs_accts  - contains  all  accounts  created  by  Parallels  H-Sphere  on  this  server 

■ hs_ftp_accts  - contains  accounts  created  by  Parallels  H-Sphere  which  are 
used  as  FTP  logins  for  Parallels  H-Sphere  users 

■ hs_iusr_accts  - contains  accounts  which  are  used  as  anonymous  for 
Parallels  H-Sphere  virtual  hosts 

■ hs_ftp_subaccts  - contains  accounts  which  are  used  as  sub  FTP  logins 

■ During  creation  of  a user,  a special  group  is  being  created  named  as  <user 
name>_group.  This  group  contains  all  accounts  related  to  a particular  Parallels  H- 
Sphere  account,  such  as  FTP  login  account,  anonymous  accounts  for  every  virtual 
host  owned  by  this  user,  and  sub  FTP  logins  accounts. 

The  following  improvements  have  been  made  to  accounts  hierarchy: 

■ a subaccount  is  no  longer  a member  of  <main  accounOg  roup 

■ <main  account  subaccts  group  is  being  created  for  each  account  that  has 
subaccounts 

■ any  subaccount  of  a particular  account  becomes  a member  of  <main 
account>  subaccts  group 

■ NTFS  permissions  to  particular  subaccount  home  directory  are  given  explicitly  for 
this  subaccount  in  addition  to  existing  NTFS  permissions  for  this  directory 
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IIS  Security  Management 

Features: 

■ The  FTP  account  login  is  not  used  anymore  as  anonymous  web  access  for  all  sites 
owned  by  the  user.  Instead  of  this,  for  each  virtual  host  a separate  account  with 
random  password  is  being  created  during  virtual  host  creation  procedure. 

■ The  password  synchronization  IIS  feature  which  requries  'local  system' 
identity  for  web  application  process  is  not  used  anymore.  The  reason  for  this  is  that 
this  account  and  randomly  generated  password  is  registered  in  the  metabase  as 
anonymous  for  this  particular  virtual  host. 

■ An  account  is  being  added  to  hs_accts,  hs_iusr_accts  and  Parallels  H-Sphere 
account  group.  Each  anonymous  login  has  the  following  format: 

<IUSR_user  name>  <virtual  host  number>  where  <username>  is  Parallels  H-Sphere  FTP 
account  title  and  <virtual  host  number>  is  number  of  particular  virtual  web  host  owned 
by  this  Parallels  H-Sphere  account. 

■ Now  each  IIS  web  application  process  is  run  under  ‘network  service’  identity. 
There  is  a number  of  Parallels  H-Sphere  modules  run  in  IIS  web  processes  which 
should  perform  some  privileged  operations  such  as  read/write  files  or  register  keys 
protected  by  NTFS  permissions.  That  is  why  Parallels  H-Sphere  creates  a special 
‘HsiSAPiAcct’  account  as  a member  of  the  ‘Local  Administrators’  group. 
This  account  is  used  by  Parallels  H-Sphere  IIS  modules  to  perform  such  privileged 
operations.  In  addition,  its  password  is  being  regenerated  each  time  IIS  is  started 
for  security  reason. 
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NTFS  permissions 

There  are  permission  schemes  which  are  used  for  Windows  2003  and  Windows  2008. 

Windows  2003/2008 

The  following  NTFS  permissions  are  set  for  a user  home  directory: 

■ Local  Administrator  group:  full  access 

■ SYSTEM:  FULL  ACCESS 

- NETWORK  SERVICE:  READ  access 

■ <FTP account name>_ group  local  group:  modify, read,  write,  execute,  list 
FOLDER  CONTENT 

The  following  permissions  are  added  to  Parallels  H-Sphere  dir>b in  directory: 

■ NETWORK  SERVICE:  READ,  EXECUTE,  LIST  FOLDER  CONTENT 


Relevant  to  both  platforms 

The  following  NTFS  permissions  are  used  for  ODBC  DSN  registry  key: 

■ Local  Administrator  group:  full  access 

■ SYSTEM:  FULL  ACCESS 

■ <FTP account na/ne>_group  local  group:  query  value,  set  value,  create 
SUBKEY, ENUMERATE  SUBKEYS , NOTI FY 


Frontpage  Server  Extensions  Management  Notes 

The  following  changes  were  made  to  FPSE  management  as  a part  of  a new  scheme: 

■ Anonymous  access  is  assigned  to  Browser  role  for  any  FPSE  enabled  virtual  host 

■ <FTP  account  na/ne>_group  local  group  is  set  as  FPSE  administrator  for  any  FPSE 
enabled  virtual  host 

■ PIsAuth  ISAPI  filter  is  no  more  used  for  FPSE  enabled  virtual  hosts 
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ASP.NET  Management  Notes 

■ The  ASP.NET  management  operations,  which  enable  and  disable  ASP.NET 
service  for  a particular  virtual  web  host,  are  based  on  the  .NET  framework 
configuration  file  machine. config. 

■ The  following  fragment  is  added  to  the  machine. config  file  for  a particular  virtual 
host  if  ASP.NET  is  being  disabled  for  this  virtual  host: 

<location  path="<virtual  host  domain  name>" 
allowOverride="f alse"> 

<system . web> 

<authorization> 

<deny  users="*"/> 

</authorization> 

</ system. web> 

</location>> 

■ When  ASP.NET  service  is  enabled  for  a particular  virtual  host,  it  is  being  removed 
from  machine  . config  file,  if  found. 


Migration  Notes 

■ During  the  Winbox  upgrade,  all  existing  accounts  will  be  automatically  migrated  to  a 
new  security  scheme.  This  process  migrates  account  settings,  web  settings,  NTFS 
permissions  for  home  directories  and  ODBC  DSNs,  ASP.NET  settings,  FPSE 
settings  and  can  take  significant  time. 

■ The  migration  procedure  is  performed  once.  If  it’s  necessary  for  some  reason  to 
repeat  the  migration,  the  NewSecurity  line  should  be  removed  from  Parallels  H- 
Sphere.NET  cf/r>bi  nins tall . history  file. 

■ Migration  process  can  be  monitored  using  migration  log  which  can  be  found  in  the 
update.log  log  file  of  upgrade  tool. 

Important:  during  the  migration,  IIS  servers  will  be  automatically  restarted  on  Windows 

2003. 


Recovery  Notes 

To  perform  server  recovery  (on  page  339)  or  server  to  server  movement,  use  the 
SetScrtNs . exe  tool  which  is  a new  analogue  of  the  SetScrt . exe  tool.  It  has  the 
same  purpose  as  the  older  version,  but  sets  the  correct  permissions  for  a new  security 
scheme. 

Download  SetScrtNs  Tool: 

http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 
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Calculating  Winbox  Traffic 

In  Parallels  H-Spherethe  system  writes  winbox  traffic  data  to  XML  logfiles: 

■ YYYY-MM-DD . web  . xml  - http  traffic, 

■ yyyy-mm-dd  . f tpg . xml  - guest  ftp  traffic, 

■ yyyy-mm-dd  . f tpa . xml  - anonymous  ftp  traffic. 

Example: 

<Traf ficEn tries > 

<DailyEn tries  Date="2005-10-28"  Type="web"> 

<Entry  Name="domainl . wincp241 . test"> 

<Incoming>7782</ Incoming> 

<Outgoing>3 90  60</ Outgo ing> 

<Hits>15</Hits> 

<HtmlHits>8</HtmlHits> 

</Entry> 

<Entry  Name="domain2 . wincp241 . test"> 

<Incoming>34  93</ Incoming> 

<Outgoing>3854  9</ Outgoing> 

<Hits>8</Hits> 

<HtmlHits>2</HtmlHits> 

</Entry> 

</DailyEntries> 

</TrafficEntries> 

These  xml  files  are  saved  to  the  C : \HSphere  . NET\data\services\traf  f ic\ 

directory.  Once  a day  TrafficLoader  (on  page  36)  parses  these  files  using  SOAP  and 

writes  statistic  data  into  the  translog  table  of  the  Parallels  H-Sphere  system 

database.  After  that  these  files  are  deleted  and  created  anew  on  the  next  day. 
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Microsoft  SQL  Server 


Microsoft  SQL,  like  other  commercial  third  party  products,  is  purchased  and  installed 
separately  from  Parallels  H-Sphere. 

Microsoft  SQL  Server  is  a fully  Web-enabled  database  with  the  ability  to  query  the 
database  through  a browser  and  rich  Extensible  Markup  Language  (XML)  support.  In 
addition,  Microsoft  SQL  Server  holds  benchmark  records  for  scalability  and  reliability, 
both  of  which  are  crucial  for  the  success  of  an  enterprise  database. 

For  extensive  coverage  of  Microsoft  SQL  Server,  please  refer  to 
http://www.microsoft.com/sgl/default.asp. 

In  this  chapter: 


Installing  Microsoft  SQL  2005  Server 251 

Moving  MS  SQL  Databases  Across  Servers 252 

Moving  MS  SQL  Databases  to  a New  Location 253 

Moving  MS  SQL  Accounts 258 
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Installing  Microsoft  SQL  2005  Server 

This  document  explains  how  to  install  MS  SQL  database  software  and  integrate  it  with 
the  Parallels  H-Sphere  system. 

Parallels  H-Sphere  2.5.0  and  higher  supports  Microsoft  SQL  Server  2005 
(http://www.microsoft.com/technet/prodtechnol/sql/2005/default.mspx). 

MS  SQL  server  can  be  installed  on  Parallels  H-Sphere  Windows  server.  This  means 
the  server  must  have  Parallels  H-Sphere  Windows  software  installed  and  be  added  to 
the  Parallels  H-Sphere  configuration. 

To  add  MS  SQL  2005  to  winbox  with  Parallels  H-Sphere  installed: 

1.  Install  ASP.NET  2.0  and  check  the  version  of  ASP.NET. 

Rootver  must  be  2.0.XXXX,  not  1 .1  .XXXX  in  the  registry 

HKLM/ Software /Microsoft/ ASP . NET. 

If  RootVer  is  1.1. XXXX: 

■ Goto  C : \Windows\Microsof  t . NET\Framework\v2 . 0 . 5xx\  through 
command  line 

■ Run  from  command  line: 
aspnet_regiis  -r 

■ Restart  IIS  : 
iisreset  /restart 

2.  Install  MS  SQL  server  following  the  directions  of  the  installation  wizard. 

If  you  installed  SQL  2005,  you  should  also  install  SQL  Server 
Management  Studio  Express. 

3.  In  SQL  Server  Managment  Studio  Express  create  login  with  system 
administrator  privileges  for  the  MS  SQL  server.  As  a rule,  login  ‘sa’  is 
used. 

4.  Configure  Parallels  H-Sphere  connection  settings  to  work  with  MS  SQL 
server: 

Note:  Parallels  H-Sphere  3.0  + uses  Windows  authentication  method  to  connect  to 
MSSQL  server.  Therefore  MSSQL  server  should  be  installed  locally  on  the  same 
server  with  Parallels  H-Sphere. 

Go  to  C:\Program  Files\HSphere\Config\hsphere.config  file  and  make  sure  the 

name_of_your_sql_server  is  set  correctly  in: 

prop  name="mssqlserver"  value="NAME  OF  YOUR  SQL  SERVER" 
description="MSSQL  server  name  or  IP" 

5.  Go  to  SQLServer  Properties  ->  Security.  Chose  SQL  Server 
Authentication  and  Windows  Authentication  to  allow  Parallels  H-Sphere 
and  your  customers  to  access  MS  SQL  server  remotely. 

6.  Make  sure  that  MS  SQL  server  IP  set  as  a logical  server  IP  in  the 

E. Manager  menu  is  set  in  Start  ->  Programs  ->  MSSQL  2005  Server  -> 
Configuration  Tools  ->  SQL  Server  Configuration  Manager  ->  SQL 
Server  Network  Configuration  ->  Protocols  for  MSSQLSERVER  -> 
TCP/IP(enabled)  ->  Properties  ->  IP  Addresses  tab.  Make  sure  this  IP  is 
there  with  Active  and  Enabled  set  to  Yes. 
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7.  In  your  CP  add  MS  SQL  server  group  to  the  physical  winboxes  with  MS 
SQL  installed. 

8.  Add  logical  MS  SQL  servers  in  CP  and  add  IP  addresses  for  it. 

9.  On  winboxes  run  the  following  commands: 

net  stop  hsphere 
net  start  hsphere 

10.  Turn  on  MS  SQL  servers  in  the  user’s  Plan  Edit  Wizard.  After  that,  try 
creating  MS  SQL  databases  from  user’s  CP. 


Moving  MS  SQL  Databases  Across 
Servers 

> To  move  the  databases  from  one  MS  SQL  server  to  another: 

1.  Install  the  new  MS  SQL  server,  keeping  the  same  path  to  databases  as 
for  the  old  server.  That  means,  databases  on  the  new  server  should  be 
located  on  the  same  disc  and  necessarily  in  the  same  directory  as  for 
the  old  server.  For  example,  on  the  old  server  data  is  located  on 

d:  \mssqi\data\,  so  the  data  on  the  new  server  should  be  located  in 
the  same  directory. 

2.  Stop  the  new  MS  SQL  server. 

3.  Copy  all  MS  SQL  database  files  including  the  “master”  database  which 
keeps  all  logins  information  and  other  necessary  information. 

Important:  All  database  files  should  be  put  into  the  same  directory  as  for  the  old 
server. 

4.  Start  the  new  MS  SQL  server. 

5.  Change  the  MS  SQL  logical  server  IP  to  the  new  MS  SQL  server  IP  in 
the  Control  Panel. 

6.  All  resellers  should  reconfigure  MS  SQL  server  aliases  to  use  the  new 
IP  for  the  MS  SQL  server. 
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Moving  MS  SQL  Databases  to  a New 
Location 


This  document  describes  how  to  change  the  location  of  the  data  and  log  files  for  any 
MS  SQL  database.  There  are  two  ways  to  move  MS  SQL  databases: 

Method  1 

(preferable) 

1 . Create  new  MS  SQL  data  location  (e  : \MSSQL\data\) 

2.  Stop  MS  SQL  server 

3.  Move  all  databases  to  a new  location  (move  *.mdf  and  *.ldf  files) 

4.  Create  junction  link  between  old  and  new  MS  SQL  data  folders.  This 
can  be  done  with  Sysinternals  Junction 

(http://download.hsphere.parallels.com/shiv/WinBox/linkmaqic.exe)  or 

any  other  utility  of  this  kind 

5.  Start  MS  SQL  server 

In  case  you  have  some  databases  with  different  from  default  locations: 

1.  Detach  these  databases 

2.  Copy  these  databases  from  old  location  to  a new  location 

3.  Attach  these  databases  from  a new  location 

Method  2 

1.  Go  to  MS  SQL  Enterprise  Manager 

2.  Choose  the  MS  SQL  server  Properties  option.  For  this,  go  to  Expand  SQL 
Server  Group  > MS  SQL  server  <SQL  Server_Name> 
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3.  On  the  Database  Settings  tab,  change  New  database  location  and  set 
the  path  to: 

■ Default  data  directory,  i.e.  a new  logical  disk  (e  : \mssql\data\) 

■ Default  log  directory  (e  : \mssql\data\) 
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4.  Create  the  following  folder  E:\mssql\data\ 

5.  Set  the  same  NTFS  permissions  as  in  the  folder  [drive]  : \Program 
Files \ Microsoft  SQL\ Server \MSSQL\ DATA  (the  path  where  DB’s 
are  located). 

6.  Go  to  MS  SQL  Enterprise  Manager  > Databases  and  right  click  on  the 
Necessary  database  > All  tasks  > Detach  Database  with  the  option  Update  statistics 
prior  detach.  Make  sure  to  check  database  and  database  log  files 
locations  before  detaching  a database. 
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7.  Go  to  [ dr ive ]: \ Program  Files\Microsoft  SQL 

Server \ms SQL \ data  and  copy  Detached  DB  files  (*.mdf  and  *.ldf)  to 
a new  folder  e : \mssql\data\ 

8.  Go  to  MS  SQL  Enterprise  Manager  > Databases  and  right  click  Databases  > 
Attach  Database. 


9.  Put  the  path  to  the  necessary  database  (e  : \mssql\data\)  and  select 
hsadmin  in  Specify  database  owner  field. 
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10. Rep 


databases. 


at  steps  6-8  for  the  rest  of 


All  necessary  information  can  be  found  in  MS  SQL  documentation 
(http://www.microsoft.com/sgl/default.mspx). 


Moving  MS  SQL  Accounts 


WARNING:  This  procedure  is  recommended  for  use  only  by  experienced  Parallels  hl- 
Sphere  administrators. 

Throughout  this  section,  all  MS  SQL  resources  of  a particular  Parallels  H-Sphere 
account  will  be  referred  to  as  MS  SQL  account.  The  following  steps  explain  how  to 
move  all  databases  of  a particular  Parallels  H-  Sphere  account  to  a new  logical  MS 
SQL  server  and  apply  changes  to  the  Parallels  H-Sphere  database. 

> To  move  an  MS  SQL  account: 

1.  Log  in  to  the  source  MS  SQL  server  and  back  up  all  user’s  databases. 

2.  Transfer  the  backup  to  the  target  server. 

3.  Log  in  to  the  target  server  and  restore  databases  from  the  backup. 

4.  Create  usernames  for  users  in  Server  > Security  > Logins. 

5.  On  the  target  server,  delete  users  from  DB  >Security  >Users  and  create 
them  again  with  the  same  name,  username,  and  database  role 
membership  as  on  the  source  server. 

6.  Create  a schema  and  assign  it  to  this  user. 

7.  Log  in  to  the  CP  server.  Change  MS  SQL  logical  server  ID  for  the 
account: 

# su  - cpanel 

# java  -Xms64M  -Xmx256M  psoft . hsphere . tools . ChangeLServerld  - 
a ACC_ID— from  OLD_LID-to  NEW_LID 

where: 

ACC  ID  is  the  account  ID 
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OLDJJD  - is  the  source  logical  MS  SQL  Server’s  ID 
NEWJJD  is  the  target  logical  MS  SQL  Server’s  ID 

8.  Restart  Parallels  H-Sphere  CP  as  described  in  Restarting  Parallels  H- 
Sphere  Control  Panel  (on  page  41). 

Make  sure  that  the  databases  function  properly  on  the  target  server.  If  everything  is 
fine,  you  can  delete  the  MS  SQL  Server  databases  from  the  source  server. 
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Dedicated  Servers 


This  chapter  tells  you  how  to  configure  MRTG  service  for  dedicated  servers. 

In  this  chapter: 

Configuring  MRTG 
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Configuring  MRTG 

In  Parallels  H-Sphere  the  MRTG  software  (http://mrtq.hdl.com/mrtq.html)  is  used  for 
the  dedicated  hosting  feature.  This  software  is  installed  to  Parallels  H-Sphere  as  a 
logical  server  from  hsphere-mrtg-rrd-x-x  package,  where  x-x  is  the  latest 
available  version. 

Mrtg  service  is  managed  by  supervise,  similarly  to  clamd,  spamd,  ftpd,  and  bind. 
Apache  service  with  configured  VirtualHost  for  mrtg  service  is  required  which  is 
provided  by  Apache  configuration. 

Mrtg  works  with  RRDtool  (http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/)  which 
improves  its  performance  and  graphing  flexibility.  RRDtool  is  used  as  the  logger  to 
MRTG.  It  stores  data  samples  on  each  of  the  network  switch  interfaces  (ports)  in  a 
separate  RRD.  To  minimize  size  of  the  database  files,  RRD  uses  the  consolidation 
mechanism.  It  guarantees  that  the  database  does  not  grow  over  time  and  that  old  data 
is  automatically  eliminated.  However  this  leads  to  degradation  of  accuracy.  For  the 
sake  of  high  degree  of  data  accuracy,  space  for  10080  samples  (35  days)  is  allocated. 
The  DSBandwidthLoader  daily  cron  acquires  data  from  RRDs  and  stores  it  into  the 
hsphere  database. 

Managing  MRTG  Service 

For  Linux: 

/etc/init.d/mrtg  stop  | start  | restart  | stat 

For  FreeBSD: 

/usr/local/etc/rc . d/mrtg . sh  stop  | start  | restart  | stat 

Configuration  Directory  and  File 

Mrtg  configuration  directory  is  /hsphere/iocai/conf  ig/mrtg. 

/hsphere/iocal/ conf  ig/mrtg/mrtg . conf  - mrtg  configuration  file.  It  has  an 
include  for  /hsphere/iocal/ conf  ig/mrtg/ports/ index  . conf  which  in  its 
turn  contains  includes  for  files  corresponding  to  each  opeational  switch  port.  Such 
files  are  generated  dynamically  via  CP  interface  when  switch  ports  are  assigned  to 
dedicated  servers. 

Scripts  Processing  Data 

/hsphere/iocal/  conf  ig/mrtg/ scripts/  get  statistics  - gathers  data  from 
each  port  file. 

/hsphere/iocal/  conf  ig/mrtg/ scripts/  setstartbill  - sets  the  Start  billing 
period  date. 

/hsphere/iocal/ conf  ig/mrtg/ scripts/ f ormgraph  - draws  traffic  graphs. 


262 


Dedicated  Servers 


RRD  Files 

Mrtg  writes  RRD  files  to  /hsphere/local/ conf  ig/mrtg/ rrd  directory.  In  its 
subdirectories  image  files  with  bandwidth  representations  for  chosen  periods  are 
located: 

■ ~httpd/htdocs/rrd/d  - day 

■ ~httpd/htdocs/rrd/w  - week 

■ ~httpd/htdocs/rrd/m  - month 

■ ~httpd/htdocs/rrd/y - year 


The  Problem  with  Calculating  Large  (>100mbps) 
Bandwidth  Traffic 

It  is  a known  issue  that  MRTG  with  32-bit  counters  doesn’t  calculate  correctly  the  traffic 
when  bandwidth  exceeds  100  Mbps.  A solution  is  to  switch  to  64-bit  counter  by 
choosing  SNMPv2c/SNMPv3  protocols.  This,  however,  may  not  work  because  some 
devices  don’t  support  these  protocols. 

> To  switch  to  SNMPv2c/SNMPv3,  you  need  to  manually  customize: 

1.  Log  into  the  CP  server  as  cpanel  user. 

2.  Copy  the  default  template  -cpanei/shiva/shiva- 
templates  / common/ ds / mrtg_targe t .config  to  the  Custom 
~ / shiva/ custom/ shiva- 

templates /common/ds /mrtg_targe t . conf ig  location.  Please 
carefully  follow  the  template  customization  procedure  described  in 
Parallels  H-Sphere  Customization  Guide. 

3.  Edit  the  first  line  with  $ {port } : $ { com_name  } @$  { device  } : 

according  to  the  MRTG  Reference  (http://oss.oetiker.ch/mrtq/doc/mrtq- 
reference.en.html). 

For  example,  to  switch  to  SNMPv2c,  the  line  will  be  like  this: 

Target [${ target }] : <if 

config. REVERSE_DEDICATED_SERVER_TRAFFIC  !=  "TRUE">- 
</if>${port}:${ com_name } @ $ { device }::::: 2 

For  more  advanced  configuration  please  refer  to  MRTG  Reference. 

4.  Restart  Parallels  H-Sphere  to  apply  customization. 
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Parallels  H-Sphere  installation  is  modular,  its  packages  independent  and  self- 
configurable.  It  is  possible  to  use  standard  package  managers  (on  page  25)  like  yum, 
up2date  or  apt-get  for  scheduled  updates  of  Parallels  H-Sphere  services,  instead 
of  running  occasional  update  scripts  or  updating  Parallels  H-Sphere  versions. 

In  this  chapter: 
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Common  Packages 

Common  packages  are  those  used  for  different  types  of  H-Sphere  servers.  For 
example,  hsphere-apache  is  installed  on  Web,  mail,  MySQL  (for  PhpMyAdmin),  and 
PostgreSQL  (for  PhpPgAdmin)  servers;  and  the  hsphere-scripts  package  is  installed  on 
every  Unix  server. 

Below  is  the  reference  on  some  common  packages. 

In  this  section: 

hsphere-info:  Collecting  Information  About  Parallels  H-Sphere  Servers  into  XML  Configs  264 


hsphere-update  Package 266 

Parallels  H-Sphere  Perl  Modules 268 

Parallels  H-Sphere  Apache 270 

Parallels  H-Sphere  PHP 281 
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hsphere-info:  Collecting  Information  About  Parallels  H- 
Sphere  Servers  into  XML  Configs 

Parallels  H-Sphere  includes  the  hsphere-info  package  installed  on  each  Parallels 
H-Sphere  Unix  server.  The  package  installs  the  /hsphere/shared/bin/hsinfo 
script  on  each  server,  and  the  script  collects  information  about  this  server  into  the 

/hsphere/ shared/ etc/ config.  xml  file. 

hsfinfo  Usage: 

hsinfo  [ -ame  ] [ -p  box  IP  ] [ -g  group  ] [ -t  type  ] [ -f  xmlfile  ] [ -s  delimiter  ] 

hsinfo  -I  [ -p  box  IP  ] [ -g  group  ] [ -s  delimiter  ] [ -f  xmlfile  ] 

hsinfo  -i  [ -ame  ] [ -g  group  ] [ -f  xmlfile  ] [ -s  delimiter  ] 

hsinfo  -n  [ -p  box  IP  ] [ -g  group  ] [ -f  xmlfile  ] 

hsinfo  -o  a[ddress]|i[nterface]|n[umber]  [ -f  xmlfile  ] 

hsinfo  -d  [ -f  xmlfile  ] 

hsinfo  -v  [ -f  xmlfile  ] 

hsinfo  -G 

hsinfo  -T 

hsinfo  -h  -I  list  of  logical  server  names 

■ i list  of  physical  server  IPs  -n  domain  name  of  the  logical  server 

■ d servise  zone  name  -p  phisical  box  IP  (default:  local  physical  box) 

■ v hspere  version 

■ a show  IP  address  -m  show  mask 

■ e show  external  IP  addreyyss 

■ o show  network  interface  name  of  the  physical  IP 

■ G list  of  possible  logical  server  groups 

■ T list  of  possible  IP  types 

■ h help 

by  default  show  only  IP  addresses 

group:  cp,  mail,  unix_hosting,  windows_hosting,  mysql,  pgsql,  mssql,  dns,  mrtg,  system 
(default:  all) 

type:  system,  service,  shared,  dedicated,  resellerSSL,  resellerDNS,  all  (default: 
service) 

xmlfile:  XML  file  location  (default:  /hsphere/shared/etc/config.xml) 

The  /hsphere/shared/etc/config.xml  file  contains  information  about  physical 
and  logical  server  names,  IDs,  IP  addresses;  system  zones;  current  Parallels  H-Sphere 
version,  etc. 

Download  sample  config. xml  from 

http://download.hsphere.parallels.com/HSdocumentation/xmls/confiq.xml. 

This  sample  XML  is  for  NAT  configured  Parallels  H-Sphere  cluster  (on  page  28). 
Otherwise,  if  external  IPs  are  used  for  H-Sphere  logical  and  physical  servers,  the  extIP 
attribute  is  omitted,  for  example: 
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<ip  type=”shared”> 

<addr>1 1 .22.33.44</addr> 
<mask>255.255.255.0</mask> 
</ip> 
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hsphere-update  Package 

The  hsphere-update  package  is  installed  on  each  Parallels  H-Sphere  box.  When 
updating  Parallels  H-Sphere,  it  runs  the  upackages  script  on  the  CP  box  to  update 
Parallels  H-Sphere  packages  on  each  box  to  their  latest  version. 

upackages  Syntax 

upackages  [ -h  ] [ -i  ] [ -f  ] [ -s  ] [ -v  version  ] [ -V  ] [ -e 

show|add:pattern,...|del:pattern,...|del:all  ] [ -p  ] [ -w  ] [ -m  ] [ -j  ] [-P]  [-r  ] [ -u  ] [ -P  ] [ -n  ] [ 
"M  ] [ -S  ] [ -R  ] [ -N  ] [ -I  ] [ -o  ] 

Where: 

■ -h  - help  information 

■ -i  - ignore  md5  sum  of  the  downloaded  packages,  only  warning 

■ -f  - force  mode,  update  packages  by  force,  when  md5  sum  of  the  installed  hsphere 
package  differs  from  downloaded  package 

■ -s  - update  only  packages  change,  which  takes  place  in  the  hsphere  subversion 
according  to  corresponding  version 

■ -v  version,  format  U[version]/U[subversion],  If  not  specified, 

/hsphere/ shared/ etc/hsversion  file  is  Checked 

■ -V  - verbose  mode 

■ -e  - [show|add:pattern1,pattern2,...|del:pattern1,pattern2,...|del:all]  - show,  set 
or  delete  a list  of  the  packages  belonging  to  a service  specified  by  pattern 
(patternN),  which  must  be  skipped  during  the  update  on  all  or  particular  HS 
boxes.  The  following  services  (patternN)  are  available  for  excluding:  dns,  mysql, 
postgresql. 

Note:  Use  this  carefully  as  HS  packages  are  connected  with  HS  version.  This  may 
be  used  if  you  have  a customized  version  of  the  specific  HS  package  or  if  you 
update  system  packages,  like  MySQL  server,  via  native  OS  package  manager,  etc. 

For  example: 

hspackages  exclude=add : my sql  ips=192 . 168 . 1 . 10 

■ -p  - PostgreSQL  update  (for  new  HS  box  this  is  done  by  default) 

■ -w  - Site  Studio  update 

■ -m  - MyDNS  service  is  used  instead  of  Bind  9.3.x,  Update  of  the  bind  will  be 
skipped. 

■ -j  - required  during  IP  migration 

■ -r  - package  update  strictly  according  to  package  list  (by  default  update  of  packages 
with  higher  version  skipped) 

■ -t  [php,httpd,ftpd, mysql, pgsql,cphttpd, named]  - place  custom  templates  in  the 
required  location  for  further  editing 

■ -P  - private  update  (for  testing  purpose) 

■ -u  - source  URL  for  packages  download  redefinition 

■ -n  - skip  restart  of  postgres  and  httpdcp  at  the  end  of  update 

■ -M  - update  modes  (presingle,  hspresingle,  postsingle,  hspostsingle, 
cpinstall,  hsupdate, postgres,  sitestudio,  update,  ipmigration, 
deploy)  : 
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■ presingle  - single  server  package  mode 

■ hspresingie  - ‘presingle’  mode,  except  sitestudio  installation 

■ postsingle  - single  server  deploy  mode 

■ hspostsingie  - ‘postsingle’  mode,  except  sitestudio  postconf 

■ cpinstaii  - control  panel  preinstall  procedure 

■ update  - full  update  (all  packages  update) 

■ hsupdate  - ‘update’  mode,  except  sitestudio  update 

■ postgres  - postgres  update 

■ sitestudio  - sitestudio  update 

■ ipmigration  - reconfiguring  IP  dependent  information 

■ deploy  - deploy  mode  (general  box  post-reconfiguration) 

■ -S  - slave  installation/update  mode  - provides  installation/update  of  web  or  mail 
slave  box 

■ -R  mask1[,mask2,...]  - revert  mode,  provides  downgrade  of  a set  of  packages  with 
mask1[,mask2,...] 

■ -N  - this  option  allows  to  force  install/update  for  the  deprecated  OS/soft  listed  in 
http://hsphere.parallels.com/eol.html,  it  possible 

■ -I  - this  option  allows  to  get  exclude  package  list  from  stdin  (used  in  HS  3.1  for 
different  update  profile  configuration  in  CP  interface).  Retrieved  package  list  is 
merged  with  pre-configured  exclude  package  list 

■ -o  - skips  pre-configured  exclude  package  list  during  update 

For  instance,  install  packages  for  Parallels  H-Sphere  2.5  Patch  6 with  md5  sum  of 
the  downloaded  files  ignored: 
upackages  -i  -v  U25 . 0/U25 . 0P6 
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Parallels  H-Sphere  Perl  Modules 

All  necessary  Perl  modules  used  by  Parallels  H-Sphere  on  supported  OS  are  installed 
from  a single  package  hsphere-perl-x-x. 

There  is  no  need  to  update  Parallels  H-Sphere  Perl  modules  by  yourself,  as  when  Perl 
version  is  updated/downgraded,  the 

/hsphere/local/ conf  ig/perl/hspmod.  switch  utility  is  used  to  switch  Perl  to  a 
proper  Parallels  H-Sphere  Perl  modules  version,  hspmod.  switch  has  the  following 
syntax: 

hspmod . switch  { -1  | -v  perl_version  } 

Where: 

-l  lists  all  possible  Parallels  H-Sphere  perl  module  versions  you  may  switch  to. 

-v  switches  to  the  modules  of  proper  perl_version,  which  must  be  specified  in  0-9.0- 
9.0-9  format. 

The  modules  for  both  native  OS  perl  and  currently  stable  perl  are  included  into  the 
latest  perl  package  update. 

To  see  the  list  of  modules  with  their  versions  for  the  specific  hsphere-peri  package, 
run  the  following  command  (specify  the  build  instead  of  x-x): 

rpm  -q— provides  hsphere-perl-x-  x 

The  above  mentioned  modules  are  installed  with  hsphere-peri  and  required  for 
proper  Parallels  H-Sphere  work. 

WARNING:  Do  not  update  or  change  any  configuration  of  your  system  Perl,  as  it  will 
most  likely  damage  your  Parallels  H-Sphere  installation. 

The  topic  below  provides  the  list  of  supported  Perl  versions. 

In  this  section: 


Supported  Perl  Versions 


269 


System  Packages  269 


Supported  Perl  Versions 

Below  is  the  list  of  Perl  packages  required  for  Parallels  H-Sphere  on  supported 
operating  systems.  Please  make  sure  that  your  operating  system  has  the  correct  Perl 
version  installed  according  to  the  following  table. 

To  check  the  version  of  Perl  installed  on  your  box,  run: 

perl  -V 


Operating  System 

Supported  Perl  Versions 

RedHat  EL  3,  CentOS  3.x,  White  Box 

EL  3.x 

Perl  5.8.0;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  4,  CentOS  4.x,  White  Box 

EL  4.x 

Perl  5.8.5;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  4,  CentOS  4.x,  White  Box 

EL  4.x  (x86_64) 

Perl  5.8.5;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  5,  CentOS  5.x 

Perl  5.8.8;  5.10.0 

RedHat  EL  5,  CentOS  5.x  (x86_64) 

Perl  5.8.8;  5.10.0 

RedHat  EL  6,  CentOS  6.x 

Perl  5.10.0,  5.10.1 

RedHat  EL  6,  CentOS  6.x  (x86_64) 

Perl  5.10.0,  5.10.1 

FreeBSD  6.1 

Perl  5.8.7;  5.8.8;  5.8.9;  5.10.0 

FreeBSD  6.2 

Perl  5.8.7;  5.8.8;  5.8.9;  5.10.0 

FreeBSD  6.3 

Perl  5.8.7;  5.8.8;  5.8.9;  5.10.0 

FreeBSD  6.4 

Perl  5.8.7;  5.8.8;  5.8.9;  5.10.0 

FreeBSD  7.0 

Perl  5.8.7;  5.8.8;  5.8.9;  5.10.0 

FreeBSD  7.1 

Perl  5.8.8;  5.8.9;  5.10.0 

FreeBSD  7.2 

Perl  5.8.9;  5.10.0 

FreeBSD  7.3 

Perl  5.10.1 

FreeBSD  7.4 

Perl  5.10.1;  5.12.4 
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Parallels  H-Sphere  Apache 

In  Parallels  H-Sphere  3.1  Beta  1 the  Web  service  functionality  was  greatly  extended 
and  improved  to  allow  for  more  flexibility  both  in  administering  Unix  web  boxes  and  in 
end  user  Web  settings. 

This  chapter  describes  the  main  features  of  the  Web  service  software  and  includes 
information  on  Apache  configuration  useful  for  Parallels  H-Sphere  system 
administrators. 

In  this  section: 


Web  Service  Packages 270 

Support  of  Apache  2.2.x  and  1 .3.x 271 

Tuning  Web  Service  from  the  CP  Interface 272 

Apache  Modules 275 

Apache  Configuration 278 

Web  Statistics  Software 280 

Apache  Logs  and  Web  T raffic  Calculation  in  Parallels  H-Sphere 280 

Log  Rotate  Config  File 280 

Apache  Suexec 280 


Web  Service  Packages 

Apache  2.2  underwent  significant  changes  since  1 .3  version.  Accordingly,  there  are 
PHP  modules  compatible  with  each  particular  Apache  version  that  is  indicated  in  the 
name  of  PHP  package  (lx  or  2x).  The  cgi/cii  part  of  PHP  is  assembled  and  works 
based  on  Apache  1 .3.  Only  the  pear  part  of  PHP  is  common  for  the  two  Apache 
versions. 

Here  is  the  list  of  web  service  software  packages  for  Parallels  H-Sphere  3.1  Beta  1 and 
up  (note  that  versions  are  just  examples  that  may  differ  from  current  ones): 


Package 

Description 

hsphere-apache2-h3 . 1-2 . 2 . 6-x 

Apache  2.2.x  binaries,  modules,  libraries  and 
headers 

hsphere-apache-h3 .1-1.3. 39-x 

Apache  1.3.x  binaries,  modules,  libraries  and 
headers 

hsphere-apache-shared-h3 . 1- 

1 — X 

Configuration  template  files,  scripts,  startup 
files,  etc.  common  for  Apache  1 .3.x  and  2.2.x 

hsphere-apache-utils-h3 . 1-1- 

X 

Utilities  used  when  parsing  apache  logs,  lynx 
browser,  etc. 

hsphere-php4-lx-4 . 4 . x-x 

hsphere-php5-lx-5 .2 .x-x 

hsphere-php5-lx-5 . 3 . x-x 

mod_php  for  Apache  1 .3.x 
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hsphere-php4-2x-4.4.x-x 

hsphere-php5-2x-5.2.x-x 

hsphere-php5-2x-5.3.x-x 

mod_php  for  Apache  2.2.x 

hsphere-php4-cgi-4.4.x-x 

hsphere-php5-cgi-5.2.x-x 

hsphere-php5-cgi-5.3.x-x 

CLI  and  CGI  PHP  binaries 

hsphere-php4-pear-4.4.x-x 

hsphere-php5-pear-5.2.x-x 

hsphere-php5-pear-5.3.x-x 

PEAR 

hsphere-php4-plugins-4.4.x-x 

hsphere-php5-plugins-5.2.x-x 

hsphere-php5-plugins-5.3.x-x 

Set  of  plugins,  their  configuration  files,  which 
may  work  in  pair  with  CLI,  CGI  or  mod_php 

Support  of  Apache  2.2.x  and  1.3.x 

In  addition  to  Apache  1 .3.x,  support  of  Apache  2.2.x  is  implemented.  There  are  two 
modes  of  Apache  2.2.x: 

■ MPM  prefork  (http://httpd.apache.Org/docs/2.2/mod/prefork.html) 

■ MPM  worker  (http://httpd.apache.Org/docs/2.2/mod/worker.html) 


For  the  MPM  worker  mode,  cgi  requests  are  processed  via  mod_cgid. 
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Tuning  Web  Service  from  the  CP  Interface 

In  Parallels  H-Sphere  3.1  Beta  1 and  up  there  is  a possibility  to  choose  some  Web 
settings  for  a physical  Web  server  right  from  administrator’s  cp  interface: 

■ switch  between  Apache  versions 

Note:  this  setting  is  available  for  all  physical  boxes. 

■ enable  additional  Apache  modules 

■ when  enabling  apache_security  module,  set  also  mod_security  options 

■ set  PHP  configuration 

■ when  enabling  fastcgi  mode,  configure  its  VirtualHost  options 

■ disable  unnecessary  PHP  plugins 

Note:  For  more  detailed  information,  refer  to  section  Advanced  Web  Server  Settings  of 
Parallels  H-Sphere  Service  Administrator  Guide. 

All  webbox  related  settings  chosen  from  the  cp  interface  are  stored  in  the  following  file: 

/hsphere/ shared/ scr ip ts/scr ip ts.cfg 

Such  changes  are  applied  immediately  by  the  script: 

/hsphere/shared/scripts/manage-service . sh  httpd  restart 

The  settings  are  stored  in  the  configuration  file  in  the  form  of  'prefix_titie=vaiue. 
There  are  several  groups  of  settings: 

In  this  section: 


Apache  Settings 272 

PHP  Settings 273 

Fastcgi  Settings 274 


Apache  Settings 

These  are  settings  for  enabling/disabling  Apache  modules.  The  prefix  is  apache.  Here 
is  the  list  of  possible  settings: 


Title 

Default  Value 

Comments 

apache_libphp4 

0 

apache_libphp5 

1 

apache_libphp53 

0 

apache_libphp54 

0 

apache_ssl 

1 

apache_scgi 

0 

apache_frontpag 

e 

0 

Ignored  in  Apache  2 

apache_throttle 

0 

Ignored  in  Apache  2 

apache_status 

0 
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apache_fastcgi  0 
apache_security  0 
apache_cache  0 

apache_security2  0 Ignored  in  Apache  1 

apache_version  1 Apache  version.  Only  for  Apache  2. 

apache_mpm  prefork  MPM  mode:  prefork  or  worker.  Only  for 

Apache  2 

All  independent  modules  are  implemented  via  specific  templates  each  allowing  for 
customization.  They  have  their  own  config  files  which  are  inserted  in  the  main  config 
file  using  the  include  directive.  The  main  config  file  is  also  realized  via  independent 
templates  for  Apache  1 .3.x  and  2.2.x. 

PHP  Settings 


For  each  Apache  version/mode  (Apache  1 .3.x  or  2.2.x  MPM  prefork  and  MPM  worker) 
there  is  a possibility  to  operate  PHP  in  6 modes:  libphpS,  iibphp4,  cgi-php5, 
cgi-php4,  f astcgi-php4 , f astcgi-php5,  libphp53,  cgi-php53,  fastcgi- 
php53,  Iibphp54,  cgi-php54,  fastcgi-php54,  Iibphp55,  cgi-php55,  fastcgi-php55.  The 
prefix  is  'php' . Here  is  the  list  of  possible  settings. 


Title 

Default  Value 

Comments 

phpjibphp4 

2 

php_fastcgi4 

0 

Needs  mod  f astcgi  to  be  enabled  for  Apache 

php_cgi4 

1 

php_libphp5 

2 

If  the  value  is  other  than  o,  the  values  for  other 
php_libphp4  options  must  be  0 

php_fastcgi5 

2 

Needs  mod_fastcgi  to  be  enabled  for  Apache 

php_cgi5 

1 

php_libphp53 

0 

If  the  value  is  other  than  0,  the  values  for  other 
phpjibphp  options  must  be  0 

php_fastcgi53 

0 

Needs  mod_fastcgi  to  be  enabled  for  Apache 

php_cgi53 

0 

php_libphp54 

0 

If  the  value  is  other  than  0,  the  values  for  other 
phpjibphp  options  must  be  0 

php_fastcgi54 

0 

Needs  modjastcgi  to  be  enabled  for  Apache 

php_cgi54 

0 

php_libphp55 

0 

If  the  value  is  other  than  0,  the  values  for  other 
phpjibphp  options  must  be  0 

php_fastcgi55 

0 

Needs  modjastcgi  to  be  enabled  for  Apache 

php_cgi55 

0 
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Fastcgi  Settings 

Fastcgi  (http://www.fastcqi.com/mod  fastcq i/docs/mod  fastcqi.htm),  unlike  the  regular 
cgi,  keeps  the  activated  module  e.g.  php  loaded  for  some  time  after  the  call.  All  further 
calls  are  carried  out  quicker  that  preserves  time  for  programs  being  loaded.  However, 
the  number  of  programs  that  can  be  stored  in  the  fastcgi  operating  memory  is 
limited. 

All  programs  loaded  by  fastcgi  are  performed  with  the  privileges  of  the  user  who 
owns  the  corresponding  virtual  host.  That  is  why  they  can  only  serve  calls  to  this 
particular  virtual  host.  This  means  that  if  all  users  will  have  fastcgi,  this  may  cause 
considerable  delays  and  enormous  increase  in  server  load. 

We  recommend  selective  approach  to  enabling  fastcgi,  i.e.  after  enabling  it  for 
heavily  visited  virtual  hosts  monitor  the  server  load  for  several  days.  If  after  such 
monitoring  the  load  is  found  permissible,  enable  fastcgi  for  more  users  and  so  on. 

The  same  is  with  with  fastcgi  parameters.  They  are  set  on  the  server  level  and  can’t 
be  changed  for  a particular  virtual  host.  There  is  not  direct  way  to  check  effectiveness 
of  these  parameters  - only  indirect  observance  based  on  server  operating.  That  is  why 
change  these  parameters  with  precaution. 


The  prefix  is  'fcgi_' . Here  is  the  list  of  possible  settings: 


Title 

Default  Value 

Comments 

autollpdate 

There  may  be  a serious  problem  when  this 
option  is  used  with  -restart. 

flush 

0 

gainValue 

0.5 

idle-timeout 

30  [seconds] 

initial-env 

FCGI_ROLE 

Allows  to  check  which  fastcgi  setting  is 
being  used.  RubyOnRails  may  need 
additional  variables. 

init-start-delay 

1 [seconds] 

killlnterval 

300 

[seconds] 

listen-queue- 

depth 

100 

maxClassProcess 

10 

It  must  be  <=  to  -maxProcesses  (this  is  not 

es 

programmatically  enforced) 

maxProcesses 

50 

It  must  be  >=  to  -maxClassProcesses  (this 
is  not  programmatically  enforced) 

minProcesses 

5 

multiThreshold 

50 

If  only  one  instance  remains, 
singleThreshold  is  used  instead 
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pass-header 

This  option  makes  available  the  contents  of 
headers  which  are  normally  not  available 
(e.g.  Authorization) 

priority 

0 

processSlack 

5 

restart 

Causes  the  process  manager  to  restart 
dynamic  applications  upon  failure  (similar 
to  static  applications) 

restart-delay 

5 [seconds] 

singleThreshold 

0 

Changing  this  is  not  recommended 
(especially  if  -appConnTimeout  is  set) 

startDelay 

3 [seconds] 

Must  be  less  than  appConnTimeout  to  be 
effective 

updatelnterval 

300 

[seconds] 

Apache  Modules 

The  core  of  hsphere-apache  contains  only  two  modules:  http  core . c and 
mod_so . c.  The  rest  are  compiled  as  DSO,  and  their  list  can  be  obtained  by  running: 

■ for  Apache  1 .3: 

Is  /hsphere/ shared/ apache/libexec/ 

■ for  Apache  2.2: 

Is  /hsphere/ shared/ apache2/modules/ 

Modules  in  different  Apache  versions  may  have  distinction  in  their  titles  and 
configuration  directives.  Apache  2.2  lacks  some  modules  present  in  1.3  version,  their 
functionalities  being  substituted  by  other  modules,  except  for  mod_throttie  and 
mod_f  rontpage  which  are  not  supported  in  2.2  version. 

Compatibility  of  Apache  1 .3  and  2.2  is  achieved  in  Parallels  H-Sphere  via  the 
mod_macro  module.  Apache  2.2  adds  several  new  modules  to  extend  functionality. 

See  below  the  comparative  list  of  modules  (the  titles  correspond  to  *.so  files): 


Apache  1.3 

Apache  2.2 

Iibphp4* 

Iibphp4* 

Iibphp5** 

Iibphp5** 

Iibphp53** 

Iibphp53** 

Iibphp54 

libproxy*** 

libssl 

mod_ssl 

mod_access 
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mod_actions  mod_actions 

mod_alias  mod_alias 

mod_asis 

mod_auth 

mod_auth_anon 

mod_auth_basic 

mod_auth_db 

mod_auth_dbm  mod_authz_dbm 

mod_auth_digest 

mod_auth_external  mod_authnz_externa 
I 

mod_auth_kerb  mod_auth_kerb 

mod_authn_anon 
mod_authn_dbd 
mod_authn_dbm 
mod_authn_default 
mod_authn_file 
mod_authz_default 
mod_authz_groupfile 
mod_authz_host 
mod_authz_owner 
mod_authz_user 

mod_autoindex  mod_autoindex 

mod_cache 

mod_cern_meta  mod_cern_meta 

mod_cgi  mod_cgi 

mod_cgid 
mod_dav 
mod_dav_fs 
mod  dbd 


mod_expires  mod_expires 

mod_ext_filter 

m od_ext  ract_f o rward  m od_ext  ract_f o rward 
ed  ed 

mod_fastcgi  mod_fastcgi 

mod_filter 

mod_frontpage 

mod_gzip 

mod_headers  mod_headers 

modjdent 
modjmagemap 

modjmap 

modjnclude  modjnclude 

modjnfo  modjnfo 

mod_log_agent 

mod_log_config  mod_log_config 

mod_log_forensic  mod_log_forensic 

mod_log_referer 

modjogio 

mod_macro  mod_macro 

mod_mem_cache 

mod_mime  mod_mime 

mod_mime_magic  mod_mime_magic 

mod_mmap_static 

mod_negotiation  mod_negotiation 

mod_psoft_traffic 

mod_rewrite  mod_rewrite 

mod_scgi  mod_scgi 

mod_security  mod_security 

mod_security2 
mod_setenvif  mod_setenvif 

mod_speling  mod_speling 

mod_status  mod_status 

mod_suexec 

mod  throttle 


mod_unique_id 

mod_unique_id 

mod_userdir 

mod_userdir 

mod_usertrack 

mod_usertrack 
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mod_version 

mod  vhost  alias  mod  vhost  alias 


Notes: 

*Part  of  the  hsphere-php5 -Xx-<PHPVER>  package  where  X is  apache  version  (1  or 
2). 

**Part  of  the  hsphere-php4-Xx-<PHPVER>  package  where  X is  apache  version  (1  or  2). 
***This  module  provides  for  an  HTTP  1.1  caching  proxy  server. 


Apache  Configuration 

Apache  1.3  Apache  2.2 

/hsphere/ shared/ apache  /hsphere/ shared/ apache2 

Comments:  Apache  home  directory 

/hsphere /local/ conf ig/httpd  /hsphere /local/ conf ig/httpd2 

Comments:  Apache  configuration  directory 

~httpd/conf  -> 

/hsphere /local /conf ig/httpd 

Comments:  The  symlink  from  home  directory 

Configuration  File 

/hsphere /local/ conf ig/httpd/ httpd . /hsphere /local/ conf ig/httpd2 /httpd 
conf  .conf 

Comments:  This  file  contains  server  wide  configuration  (modules  enabled,  their  parameters 
set  etc.).  We  don’t  recommend  that  changes  are  made  to  this  file. 

When  Apache  modules  are  enable/disabled  from  the  interface,  the  configuration  files  are  left 
unchanged.  This  interface  feature  is  implemented  via  the  comand  line  Apache  using 
<if Define  . . . > directives  and  corresponding  global  symbols. 

These  files  are  customized  using  config  file  templates. 

More  on  config  file  template  customization  read  in  Appendix  C of  Parallels  H-Sphere 
Installation  Guide. 

Custom  Configuration  File 

/hsphere /local /conf ig/httpd/ custom  /hsphere /local /conf ig/httpd2/custo 
.conf  m.conf 

Comments:  We  recommend  that  this  file  is  used  for  making  changes  to  the  wide  configuration, 
and  for  enabling  additional  modules  in  particular.  This  may  facilitate  finding  configuration  errors 
in  case  the  server  cannot  start. 

When  Apache  is  launched,  the  custom  configuration  file  is  the  second  to  be  processed  after 
httpd.  conf.  After  that,  virtual  hosts  configuration  is  picked  up. 

System  Virtual  Hosts  Config 

/hsphere /local/ conf ig/httpd/ namevh  /hsphere /local/ conf ig/httpd2 / namev 
.conf  h.conf 
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Comments:  This  file  contains  list  of  all  system  (not  user!)  virtual  hosts.  Apache  supports  virtual 
host  of  3 types  - name-  based,  IP-based  and  port-based.  Parallels  H-Sphere  uses  name-based 
virtual  hosts  by  default  but  the  other  types  can  be  used  as  well.  The  configuration  file  contains 
information  on  host  type  for  each  IP.  This  file  is  processed  after  custom,  conf  but  before 


processing  the  configuration  of  virtual  hosts. 


Virtual  Hosts  (Logical  Servers)  Configs 

/hsphere/local/conf ig/ht tpd/ conf /I 

/hsphere/local/conf ig/ht tpd2/ conf / 

servers/ 

lservers/ 

mail. conf,  mrtg.conf. 

mail. conf,  mrtg.conf. 

mysql . conf . . . 

mysql . conf . . . 

Comments:  For  each  logical  server  a virtual  host  is  created.  Before,  when  accessing  the  box 
by  its  logical  name  it  was  possible  to  view,  for  instance,  sources  of  phpMyAdmin.  Now  with 
each  logical  name  having  its  own  virtual  host  such  a possibility  is  eliminated. 

These  files  are  customized  using  templates. 

More  on  config  file  template  customization  read  in  Appendix  C of  Parallels  H-Sphere 
Installation  Guide. 


/hsphere/local/conf ig/httpd/ sites/ 

Comments:  This  directory  contains  files  for  user  virtual  hosts.  A link  to  this  directory  is 
included  to  the  configuration  directory  of  Apache  2.2.  This  means  that  configuration  files  of 
user  virtual  host  are  common  for  the  two  Apache  versions. 

Syntactical  differences  in  directives  between  1.3  and  2.2  versions  are  leveled  by  mod  macro 
module  introduced  in  Parallels  H-Sphere  3.1  and  up,  i.e.  macros  are  used  instead  of 
configuration  directives,  mod  macro  is  a third-party  module  to  the  Apache  Http  Server 
distributed  with  a BSD-style  license  like  Apache.  It  allows  the  definition  and  use  of  macros 
within  Apache  runtime  configuration  files.  The  syntax  is  a natural  extension  to  apache  html-like 
configuration  style. 

Macros  are  placed  to  . /macro  of  the  Apache  configuration  directory.  Macros  for  Apache  1 .3 
are  different  from  those  for  Apache  2.2. 
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Web  Statistics  Software 
Apache  2.2.x 

General  web  statistics  is  gathered  using  general  mod_iog_conf  ig  and  mod  iogio 
modules.  mod_iog_config  is  patched  to  provide  logging  to  the  server  log  even  if 
custom  logs  are  redefined  at  the  virtual  host  level.  For  this  purpose, 
AlwaysServerLogs  directive  is  added. 

Apache  1.3.x 

General  web  statistics  is  gathered  using  the  mod_psoft_traf f ic  apache  module. 

Apache  Logs  and  Web  Traffic  Calculation  in  Parallels  H-Sphere 

Apache  logs  are  located  in  the  /hsphere/iocai/var/httpd/iogs/  directory.  Also, 
each  hosted  Web  domain  has  its  own  logs  in  the 

/hsphere / local  /home /<user> / logs  / <domain.name> / directory  (see  Web  traffic 
calculation  (on  page  116)). 

There  are  two  types  of  Web  traffic  calculation  in  Parallels  H-Sphere: 

■ third-party  traffic  calculation  - Parallels  Pi-Sphere  writes  traffic  log  files  to  each 
domain’s  directory  to  make  them  available  for  third-party  log  analyzers:  Webalizer, 
Modlogan,  and  AWStats 

■ Parallels  Fl-Sphere  built-in  traffic  calculation  - Parallels  Pi-Sphere  provides  its  own 
mechanism  of  traffic  calculation  used  in  billing. 

Please  refer  to  a separate  section  on  Web  traffic  calculation  and  log  rotation  (on  page 
116). 

Log  Rotate  Config  File 

/hsphere/local/ conf  ig/httpd/ rotatelog . cf g - log  rotate  COnfig  file  which 
includes  all  log  confs  located  in  the 

/hsphere/local/  conf  ig/httpd/ logrotate_conf  / directory: 

■ <cfo/na/'n.na/77e>.transferiog.conf  - config  file  for  transfer  log  rotation  for  a 
domain 

■ <domain.name> . erroriog . conf  - config  file  for  error  log  rotation  for  a domain 

■ <domain.name> . agentiog . conf  - config  file  for  agent  log  rotation  for  a domain 

■ <domain.name> . ref  erreriog . conf  - config  file  for  referrer  log  rotation  for  a 
domain 


Apache  Suexec 

Parallels  Fl-Sphere  WebBox  Apache  suexec  is  configured  to  run  users’  CGI  scripts  only 
within  the  /hsphere/local /home/  directory,  recursively.  Thus,  a user  may  run 
his/her  own  cgi  scripts  only  if  he/she  has  fourth  nesting  level  within  the  Parallels  Fl- 
Sphere  user  home  directory,  for  example,  /hsphere/iocai/home/user_homei. 


System  Packages  281 


Parallels  H-Sphere  PHP 


PHP  is  assembled  into  separate  Parallels  H-Sphere  packages: 


Package 

Description 

hsphere-php4-1x-<version> 

hsphere-php5-1x-<version> 

mod_php  for  Apache  1 .3.x 

hsphere-php4-2x-<version> 

hsphere-php5-2x-<version> 

mod_php  for  Apache  2.2.x 

hsphere-php4-cgi-<version> 

hsphere-php5-cgi-<version> 

CLI  and  CGI  php  binaries 

hsphere-php4-pear-<version> 

hsphere-php5-pear-<version> 

PEAR  for  PHP 

hsphere-php4-plugins-<version> 

hsphere-php5-plugins-<version> 

Set  of  plugins,  their  confs,  which  may  work  in 
pair  with  CLI,  CGI  or  mod_php 

hsphere-php53-<version> 

United  PHP  5.3  package 

hsphere-php54-<version> 

United  PHP  5.4  package 

hsphere-php55-<version> 

United  PHP  5.5  package 

hsphere-php-internal 

PHP  build  used  for  mail/DB  web  interfaces 

In  this  section: 


Configuring  PHP  from  the  Interface 281 

PHP  Components 282 

Objects  in  PHP  5 282 

PHP  Thread  Safety 283 

Standardized  PHP 283 

PHP  Test  Page 283 

Customizing  php.ini  Configuration  File 283 

PHP  Modules  Installed  with  Parallels  H-Sphere  PHP  Packages 283 

Configuring  PHP  Safe  Mode 288 

Adding  PHP  Extensions 289 


Configuring  PHP  from  the  Interface 

In  Parallels  H-Sphere  3.6.3  and  later,  administrators  can  adjust  many  PHP  settings  and 
users  can  choose  between  PHP  versions  4,  5,  5.3,  5.4,  and  5.5.  Note  that  PHP  4 is  not 
available  on  RHEL/CentOS  6. 

To  learn  more  about  this,  refer  to  the  section  Apache  in  Parallels  H-Sphere  3.1+  (on 
page  270). 
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PHP  Components 
Ldap 

Ldap  support  has  been  included  to  php-core,  which  is  one  of  the  reasons  why  horde 
may  start  to  slow  down  when  sending  mail.  It  happens  because  horde  is  trying  to 
connect  to  available  ldap  servers  that  are  very  slow  by  themselves. 

Pear 

Another  important  peculiarity  of  the  new  PHP  packages  is  support  of  pear.  To  view 
which  packages  from  pear  repository  have  been  installed,  run: 

/hsphere/ shared/phpX/bin/pear  list 

To  view  the  list  of  all  pear  packages  available  in  the  repository,  run: 

pear  list-all 

To  check  which  pear  packages  need  to  be  upgraded,  run: 

pear  list-upgrades 

To  upgrade  all  pear  packages  installed,  run: 

pear  upgrade -all 

Peel 

As  for  the  PECL  repository,  2 packages  from  it  (Fileinfo  and  SQLite)  have  been 
included  to  PHP4  and  one  (Fileinfo)  to  PHP5.  In  PHP5,  SQLite  is  supported  from  php- 
core. 

Objects  in  PHP  5 

PHP5  has  undergone  some  principal  changes  in  the  way  it  works  with  objects.  That  is 
why  some  programs  that  work  fine  with  PHP4  may  not  work  with  PHP5.  To  ensure 
PHP5  support,  all  third-party  products  included  to  Parallels  H-Sphere  have  been 
updated  to  the  latest  available  version. 
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PHP  Thread  Safety 

Since  Parallels  H-Sphere  3.6.3,  PHP  5.3,  5.4,  and  5.5  are  built  thread-safe  only  when 
needed  (Apache  2 with  lib_php  and  worker  MPM).  Thread-safe  PHP  binaries  have  their 
own  configuration  separated  from  non-thread-safe  ones  and  referenced  in  the 
documentation  as  php53_ts,  php54_ts,  and  php55_ts. 

Standardized  PHP 

Since  Parallels  H-Sphere  3.6.2,  a dedicated  PHP  build  is  used  in  CGI/FCGI  mode 
(depending  on  whether  FCGI  is  enabled  or  not)  for  mail/DB/file  manager  web  interfaces 
such  as  Horde,  phpMyAdmin,  phpPgAdmin  and  WebShell,  so  these  applications  can 
be  configured  independently  from  end-user  PHP  settings. 

PHP  Test  Page 

New  PHP  packages  have  been  assembled  to  perfectly  fit  mail  web-interfaces,  and 
horde  in  particular.  This  means  that  PHP  test  page  can  be  obtained  from 
http:/<box_/P>/horde/test.php.  Here,  pay  attention  to  memory_iimit  value.  We 
recommend  that  it  is  either  -1  (disabled)  or  8 MB. 


Customizing  php.ini  Configuration  File 

If  you  want  to  customize  PHP  config  files  for  PHP  4 and  PHP  5,  please  refer  to 
Appendix  C.  Customizing  Server  Configuration  Files  By  Means  of  Templates  of 
Parallels  H-Sphere  Installation  Guide. 

PHP  Modules  Installed  with  Parallels  H-Sphere  PHP  Packages 


Standard  PHP  Installation  has  the  following  modules  enabled: 


PHP  extensions 

php4 

php5 

before  4.4.4 

4.4.4+ 

before  5.1.6 

5.1.6+ 

bcmath 

so 

so 

so 

so 

bz2 

so 

core 

so 

core 

calendar 

so 

so 

so 

so 

ctype 

core 

core 

core 

core 

curl 

so 

so 

so 

so 

date 

- 

- 

core 

core 

dba 

core 

core 

core 

core 

dbase 

so 

so 

so 

so 

dbx 

so 

so 

- 

- 

dom 

- 

- 

core 

core 

domxml 

so 

so 

- 

- 

exit 

so 

so 

- 

so 

fileinfo 

so 

so 

so 

so 

filepro 

so 

so 

so 

* 

ftp 

so 

core 

so 

core 

gd 

so 

core 

so 

core 

gettext 

so 

core 

so 

core 

gmp 

so 

so 

so 

so 

hash 

- 

- 

core 

core 

iconv 

so 

so 

so 

so 

Imap 

so 

so 

so 

so 

Idap 

core 

so 

core 

so 

libxml 

- 

- 

core 

core 

mbstrlng 

core 

core 

core 

core 

meal 

so 

so 

- 

★ 

mcrypt 


so 


core 


so 


core 
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mhash 

so 

core 

so 

core 

mime_magic 

core 

core 

core 

core 

mnogosearch 

so 

so 

so 

so 

mysql 

so 

so 

so 

so 

mysqli 

- 

- 

- 

so 

n curses 

so 

so 

so 

so 

odbc 

so 

so 

so 

so 

openssl 

core 

core 

core 

core 

overload 

core 

core 

- 

★ 

pcntl 

so 

so 

so 

so 

pdf 

so 

so 

- 

- 

pcre 

core 

core 

core 

core 

PDO 

- 

- 

core 

core 

pgsql 

so 

so 

so 

so 

posix 

core 

core 

core 

core 

pspell 

so 

so 

so 

so 

Reflection 

- 

- 

core 

core 

session 

core 

core 

core 

core 

shmop 

so 

so 

so 

so 

SimpleXML 

- 

- 

core 

core 

soap 

- 

- 

so 

so 

sockets 

core 

core 

so 

core 

SPL 

- 

- 

core 

core 

sqlite 

so 

so 

core 

so 

standard 

core 

core 

core 

core 

swf 


removed 


sysvmsg 

so 

so 

so 

so 

sysvsem 

so 

so 

so 

so 

sysvshm 

so 

so 

so 

so 

tokenizer 

core 

core 

core 

core 

xml 

core 

core 

core 

core 

xmlrpc 

so 

so 

so 

so 

xmlreader 

- 

- 

core 

core 

xmlwriter 

- 

- 

core 

core 

xsl 

- 

- 

core 

core 

xslt 

so 

so 

- 

- 

yp 

so 

so 

- 

* 

zip 

so 

core 

- 

- 

zlib 


core 


core 


core 


core 


Detailed  information  on  PHP  modules  find  in  PHP  Manual, 
http://www.php.net/manual/en/ 
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Notes: 


■ meal  extension  has  been  moved  to  the  PECL  repository  (http://pecl.php.net/)  and  is 
no  longer  bundled  with  PHP  as  of  version  5.0.0. 

■ yp  extension  has  been  moved  to  the  PECL  repository  and  is  no  longer  bundled  with 
PHP  as  of  version  5.1.0. 

■ filepro  extension  has  been  moved  to  the  PECL  repository  and  is  no  longer  bundled 
with  PHP  since  version  5.2.0. 

■ overload  extension:  see  the  page 

http://www.php.net/manual/en/language.oop5.overloading.php  for  more  information. 

■ PHP  5.3  has  the  following  extensions  (all  of  them  are  enabled  by  default): 
bemath  bz2  calendar  cgi-fcgi  ctype  curl  date  dba  dom  ereg  exit  fileinfo  filter  ftp  gd 
gettext  gmp  hash  iconv  imap  json  libxml  mbstring  mcrypt  mhash  mnogosearch 
mysql  mysqli  odbc  openssl  pore  PDO  pdo_pgsql  pdo_sqlite  pgsql  Phar  posix 
Reflection  session  SimpleXML  sockets  SPL  SQLite  sqlite3  standard  tokenizer  xml 
xmlreader  xmlwriter  xsl  zlib 

PHP  Modules  Default  Location 

To  find  out  the  default  location  of  PHP  modules,  issue  the  following  command: 

# /hsphere/ shared/php<PHP\/ERS/OA/>/bin/php-conf ig— extension-dir 

For  PHP  versions  earlier  than  5.3,  this  directory  is  linked  to  hsphere  catalogue 
Structure  /hsphere/ shared/apache/libexec/php<PHP\/E/?S/OW>ext 

To  list  installed  so-modules,  run: 

# Is  /hsphere/shared/apache/libexec/php<PHPVERSION>ext/* . so 

Enabling/Disabling  PHP  Modules 

Modules  are  added  one  by  one  with  ini-files  of  the  same  name  that  can  be  found  in 

/hsphere /local/ conf  ig/httpd/php <PHPVERSION> / php . d 

If  an  ini-file  contains  extension=extname . so  line,  php  at  startup  loads  a 
corresponding  extension  module.  Mind,  any  text  following  an  unquoted  semicolon  is 
ignored,  thus  the  module  indicated  in  the  line;  extension=extname . so  won’t  load. 

At  updates  coming  after  hsphere-php4-4.4.4-2  ini-files  are  not  overwritten  (as  in  earlier 
versions),  but  remain  unchanged.  Only  for  extensions  that  do  not  have  corresponding 
ini-file,  ini-files  are  created  according  to  the  procedure  above. 

php.info 

php. info  gathers  info  on  php  core,  modules,  apache  environment  etc.  You  can  run  it  as 
console  command: 

/hsphere/shared/php4/bin/php-cli  -i  | less 
or  screen  its  output  at  http://<box_ip>/hsphpinfo.php 
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Configuring  PHP  Safe  Mode 

Important:  PHP  safe  mode  is  not  supported,  deprecated  in  PHP  5.3,  and  removed  in 
PHP  5.4.  You  can  use  it  at  your  own  risk. 

PHP  safe  mode  is  turned  off  by  default  in  the  original  Parallels  H-Sphere  configuration. 

To  turn  it  on,  set  safe_mode=On  in  the  php . ini  file  (usually,  in  the 

/us  r/ local /lib  directory).  Please  note  that  php. ini  must  be  customized  by  means 

of  the  respective  custom  config  file  template. 

> To  use  default  Parallels  H-Sphere  configuration  for  PHP  with  safe  mode 
on: 

1 . Take  the  default  php . ini  installed  with  standard  Parallels  H-Sphere 
PHP  packages. 

2.  Turn  the  safe  mode  on. 

3.  Copy  that  file  to  the  PHP  installation  directory  (usually, 

/usr/ local/ lib). 

Read  more  on  PHP  safe  mode  configuration  in  PHP  documentation 
(http://www.php.net/manual/en/features.safe-mode.php#ini.safe-mode). 

To  turn  the  safe  mode  off  for  an  individual  account,  edit/add  the  following  directives  in 

the  /hsphere/iocai/conf ig/httpd/httpd.  conf  Apache  configuration  file  on 
the  Web  server. 

<Di rectory  /hsphere /local/ home /wwwuser> 

<If Module  mod_php4.c> 

php  admin_flag  safe_mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

<If Module  mod_php5.c> 

php  admin_flag  safe_mode  off 

php  admin^value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

</Directory> 

To  have  IMP  Horde  web  mail  (on  page  132)  working  when  the  safe  mode  is  on,  set  the 
following  directive  in  /hsphere /local/  conf  ig/httpd/httpd  .conf  on  the  Web 

server  and  make  changes  in  the  respective  custom  configuration  file  template): 

<Directory  /hsphere/ shared/ apache/htdocs/horde> 

<If Module  mod_php4.c> 

php  admin_flag  safe_mode  off 

php  admin_value  upload^tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

<If Module  mod_php5.c> 

php  admin_flag  safe_mode  off 

php  admin_value  upload_tmp  dir  "/tmp" 

php  admin^value  session . save_path  "/tmp" 

</ IfModule> 

</Directory> 
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To  configure  Webshell  4 (on  page  109)  so  that  it  would  work  with  the  safe  mode 
globally  on: 

<Directory  /hsphere/ shared/ apache/htdocs/webshell4> 

<If Module  mod_php4.c> 

php  admin_flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

<If Module  mod_php5.c> 

php  admin^flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule></Directory> 

Restart  Apache  (on  page  42)  after  performing  necessary  modifications. 

Adding  PHP  Extensions 

PHP  4 and  PHP  5 packages  include  almost  all  commonly  used  extensions.  So,  before 
you  start  re-compiling  PHP,  make  sure  that  an  extension  you  need  to  add  is  indeed 
absent.  See  the  list  of  modules  included  in  PHP  4 and  PHP  5 (on  page  283). 

In  this  section: 
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Adding  New  Extensions 290 

Adding  PEAR  Modules 290 

Adding  PECL  Modules 290 
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Compilation  Requirements 

Before  the  compilation,  check  that  the  following  libraries  are  installed: 

■ autoconf 

■ automake 

■ libtool 

■ zlib-devel 

■ mysql-devel 

■ postgresql-devel 

Other  required  libraries  are  listed  in  the  documentation  to  respective  modules. 

Please  also  take  into  account  that  PHP  4 and  PHP  5 have  different  module  structures. 
For  example,  the  domxml  module  of  PHP  4 is  absent  in  PHP  5. 
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Adding  New  Extensions 

PHP  packages  are  built  from  modules.  To  include  a new  module,  use  phpize  in  the 
following  way: 

# tar  zxf  your_module.tgz 

# cd  yourjmodule 

# /hsphere/shared/<PHP  version>/bin/phpize 

# . /configure—- with-php-conf ig=/hsphere/ shared/ <PHPVERSION> /bin/php- 
conf ig 

# make 

# make  install 

<PHP  VERSION>  is  php4 , php5,  php53,  php53_ts,  php54,  php54_ts,  or  php-internal 
depending  on  the  PHP  version. 

To  find  out  where  a new  extension  is  compiled  to  and  where  all  other  PHP  extensions 
are  located,  run: 

# /hsphere/ shared/<PHPVERSION>/bin/php-conf ig— extension-dir 

Aslo  you  can  use  additional  options  in  configuration  string,  for  example: 

. /configure— with-php-conf ig=/hsphere/ shared/php4/bin/php-conf ig— with- 
mssql=/usr / local /freetds— enable-msdblib 


Adding  PEAR  Modules 

To  install  PEAR  modules,  run: 

# /hsphere/shared/<PHPVERSION>/bin/pear  install  your_module 

Read  the  PEAR  Command  line  installer 

(http://pear.php.net/manual/en/installation.cli.php)  documentation  for  details. 


Adding  PECL  Modules 

PECL  modules  can  be  installed  either  by  phpize  or  by  pear.  See  Installation  of 
PECL  extensions  (http://www.php.net/manual/en/install.pecl.php)  in  PHP  Guide. 
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Enabling/Disabling  Built-in  PHP  Modules 

Modules  that  are  installed  with  PHP  packages  are  enabled  by  default. 

> To  disable  (or  enable)  a module: 

1.  Go  to  the  directory  where  respective  .ini  file  for  a module  is  located: 

# cd  /hsphere/local/config/httpd/<P/-/Pt/ERS/OA/>/php.d/ 

Here,  <PHPVERSION>  is  php4  or  php5. 

For  PHP  5.3,  5.4,  and  5.5  you  should  use: 

# cd  /hsphere/local/config/httpd/<PHPVERSION>/php.d/ 

Here,  <PHPVERSION>  is  php53,  php53_ts,  php54,  php54_ts,  php55,  or  php55_ts. 

1.  Open  the  <module_name> . ini  file  for  editing.  See  the  list  of  PHP 
modules  (on  page  283). 

2.  Comment  the  line  extension=<module_name> . so  to  disable  the 
module: 

; extension=<module  name>.so 

Uncomment  this  line  to  enable  the  module. 

3.  Restart  Apache  (on  page  42)  on  the  Web  server  to  apply  changes. 


Parallels  SiteStudio  Packages 

Parallels  SiteStudio  is  installed  in  two  separate  Parallels  H-Sphere  packages: 

■ hsphe  re  -sitestudio-  co  re -<version> 

hsphere-sitestudio-tempiates-<vers/on>  To  install  Parallels  SiteStudio 
packages,  go  to  /hsphere/instaii  and  run: 

make  ss-install 

This  command  launches  the  script  which  downloads  and  installs  the  necessary 
packages  (e.g.  xorg-xii-libs)  and  then  installs  Parallels  SiteStudio. 

Imaker  is  run  under  the  imaker  user  (not  root!). 

If  previous  Parallels  SiteStudio  version  was  installed  from  a . tgz  archive,  the  new  one 
is  installed  over  it  without  uninstalling  the  older  version. 
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Load  Balancing 


It  is  possible  to  add  load  balanced  (LB)  Web  and  mail  clusters  to  Parallels  H-Sphere. 
Load  balancing  implies  balancing  server  traffic  amongst  multiple  computers  (LB 
cluster)  which  Parallels  H-Sphere  regards  and  operates  with  as  a single  server. 

Load  balanced  cluster  solution  in  Parallels  H-Sphere  requires  4 or  more  physical 
servers: 

■ Load  Balancer:  any  solution  like  Cytrix®  NetScaler 
(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314)  for 

balancing  traffic  across  the  web/mail  servers.  Load  Balancer  directs  traffic  to 
another  server  if  the  first  one  is  currently  overloaded.  It  can  also  allow  the  service  to 
continue  even  if  one  of  the  servers  is  down. 

■ One  master  and  one  or  more  slave  servers  form  a load  balanced  Web/mail  cluster. 
All  these  servers  are  being  added  to  Parallels  H-Sphere  as  physical  servers,  with  all 
related  packages  installed,  but  Parallels  H-Sphere  logical  servers  are  created  only 
on  master  servers,  and  Parallels  H-Sphere  operates  with  load  balanced  cluster  only 
via  master  server. 

■ NAS  (Network  Attached  Storage):  shared  storage  for  master  and  slave  servers. 

NAS  is  a highly  reliable  server  with  enough  space  for  storing  data.  Web/mail 
content  directories  are  mounted  to  the  NAS  where  the  content  is  actually  stored. 
Web  and  mail  servers  can  jointly  use  one  NAS  or  have  their  own  NAS  for  Web  and 
for  mail. 

Figure  1:  Simple  Load  Balanced  system  with  one  Web  cluster: 
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Figure  2:  More  complex  Load  Balanced  system  with  two  mail  and  two  web  clusters: 
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Load  Balancers 

You  need  to  purchase,  install  and  configure  any  load  balancer  solution,  for  example, 
Cytrix®  NetScaler 

(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314). 

This  task  is  beyond  the  scope  of  Parallels  H-Sphere  documentation. 


Supported  NAS 


The  following  file  storage  systems  (on  page  308)  are  supported  by  Parallels  H-Sphere: 


NAS 

Notation 

Supported  in  Parallels  H-Sphere 

Generic  Linux  NFS  (on  page 
300) 

UNIX 

3.0  RC  1 and  up 

RedHat  GFS  (on  page  300) 

UNIX 

3.0  RC  4 and  up 

NetApp 

(http://www.netapp.com/produ 

cts/filer/) 

NET  APP 

2.3  and  up  to  2.5 

3.0  RC  1 and  up 

BlueArc 

(http://www.bluearc.com/) 

BLUE  ARC 

2.4.3  Patch  10  and  up 

2.5  Beta  5 and  up 

EMC  Celerra 

(http://www.emc.com/products/ 

networkinq/servers/index.isp) 

EMC  CELERRA 

2.4.3  Patch  10  and  up 

2.5  Beta  5 and  up 

Note:  All  Parallels  H-Sphere  customers  will  be  recommended  to  choose  shared  Linux 
NFS  as  the  most  simple  and  reliable  solution. 


Load  Balanced  Cluster 

Loab  balanced  cluster  consists  of  one  master  and  one  or  more  slave  servers  regarded 

by  Parallels  H-Sphere  as  a single  server. 

■ Master  and  slave  servers  are  added  to  Parallels  H-Sphere  as  physical  servers. 

■ Master-slave  relations  between  these  servers  are  set  in  admin  CP. 

■ Only  master  server  is  added  as  Web/mail  logical  server  to  Parallels  H-Sphere.  CP 
communicates  only  with  master  server. 

■ Requests  are  passed  to  external  IPs  routed  by  the  load  balancer.  Load  balancer 
distributes  requests  evenly  across  the  master  and  slave  servers  (internal  IPs 
corresponding  to  external  IP).  For  this  purpose,  NAT  must  be  properly  configured 
on  load  balanced  cluster  servers. 
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■ Master  and  slave  server  share  the  same  Parallels  H-Sphere  related  directories 
where  all  user  content,  scripts,  and  the  majority  of  Parallels  H-Sphere  related 
binaries  are  located.  These  directories  are  actually  stored  on  the  NAS  and  mounted 
from  master  and  slave  servers  via  NFS. 

■ Along  with  shared  storage,  master  and  slave  servers  have  their  own  unique  IP- 
specific  logs  and  configs  which  are  synchronized  by  special  cron  scripts  run  on 
these  servers. 

See  load  balanced  cluster  scheme  with  generic  Linux  NFS  shared  storage  (on  page 

295). 

In  this  chapter: 


Implementation  of  Load  Balanced  Cluster  in  Parallels  Fl-Sphere 295 

Load  Balancing  Support  in  Parallels  Fl-Sphere 300 

Installing  Load  Balanced  Web/Mail  Clusters  in  Parallels  Fl-Sphere 300 
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Implementation  of  Load  Balanced  Cluster 
in  Parallels  H-Sphere 

This  section  describes  load  balanced  Web/mail  cluster  scheme  for  generic  Linux  NFS 
(on  page  300)  NAS. 


In  this  section: 


Load  Balanced  Cluster  in  CP 295 

Distribution  of  Requests  Across  Load  Balanced  Cluster 296 

Shared  Content 296 

Specific  Master/Slave  Content 297 

Synchronization  Between  Master  and  Slave  Servers 297 

Traffic  Calculation 298 

Load  Balanced  Cluster  Map 299 

NAT  Configuration  for  Load  Balanced  Clusters 299 


Load  Balanced  Cluster  in  CP 

■ Master  and  slave  servers  are  added  to  Parallels  Fl-Sphere  as  physical  servers. 

■ Master-slave  relations  between  these  servers  are  set  in  admin  CP. 

■ Only  master  server  is  added  as  Web/mail  logical  server  to  Parallels  Fl-Sphere.  CP 
communicates  only  with  master  server. 
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Distribution  of  Requests  Across  Load  Balanced  Cluster 

Parallels  H-Sphere  regards  Web  or  mail  load  balanced  cluster  as  a single  server. 
Requests  are  passed  to  external  IPs  routed  by  the  load  balancer.  Load  balancer 
distributes  requests  evenly  across  the  master  and  slave  servers  (internal  IPs 
corresponding  to  external  IP). 

Shared  Content 

Master  and  slave  servers  share  the  same  /hsphere  directory  mounted  by  NFS  to  the 
/filer / <cluster_type>  <cluster_id> / directory  on  the  NAS  where  load  balanced 
cluster  content  is  actually  stored.  Plere,  <cluster_type>  is  mail  or  web,  and  <cluster_id>  is 
cluster  id  - there  may  be  multiple  load  balanced  clusters  mounted  to  the  NAS:  01 , 02, 

...  (See  the  illustration  (on  page  292)  for  2 Web  and  2 mail  clusters.) 

All  user  content,  scripts,  and  the  majority  of  Parallels  Pi-Sphere  related  binaries  are 
installed  into  the  /hsphere  directory  and  shared  by  master  and  all  slaves. 

Follow  the  Adding  Load  Balanced  Clusters  on  Shared  Linux  NFS  (on  page  300) 
instructions  to  learn  how  to  correctly  mount  the  shared  storage  on  the  NAS  to  the 
master  and  slave  servers. 
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Specific  Master/Slave  Content 

Along  with  the  common  shared  storage,  master  and  slave  servers  have  their  own 
Parallels  H-Sphere  specific  (Apache,  FTP)  and  IP-dependent  (network)  logs  and 
configuration: 

■ Both  master  and  slave  servers  have  unique  Apache  logs  stored  locally  in  the 
/var/iog/hsphere/httpd  directory  instead  of  the  default 

/hsphere/local/var/httpd/ logs  directory. 

■ On  the  master  server,  Apache,  FTP  and  network  configuration  is  located  in  the 
/hsphere  directory  (which  is  a mountpoint  to  the  NAS  and  is  common  for  the  master 
and  the  slave  servers): 

/hsphere /local/ conf ig/httpd/ 

/hsphere /local/ conf ig/ f tpd/ 

/hsphere /local /network/ 

On  slave  servers,  however,  this  data  is  unique  and  is  stored  locally  in  the 

/etc/hsphere  directory: 

/ etc/hsphere/httpd/ 

/ etc/hsphere/ f tpd/ 

/ etc/hsphere /network/ 

Parallels  Pi-Sphere  updater  running  with  the  hspackages  siaves=web  | mail  | all 
option  creates  the  /etc/hsphere  directory  data  on  slave  servers. 

Synchronization  Between  Master  and  Slave  Servers 

The  special  cron  script  /hsphere/ shared/ scripts/ cron/lb_sync  . sh  runs  each 
minute  on  each  slave  server  to  synchronize  data  on  master  and  slave  servers.  It 
parses  and  synchronizes: 

■ User  Apache/ProFTPd  config  files 

/ etc/hsphere/ [httpd | f tpd] /sites/*. conf,  and 
/ etc/hsphere /network/ ips 

■ the  /etc/passwd,  /etc/shadow,  /etc/group  files. 
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Traffic  Calculation 

User  logs  are  located  in  the  /hsphere /local /home /<USer>/logs/ domain  . com/ 

directory.  On  master  server,  log  filenames  look  like: 

{ domain . name } 
referrer  log 
access_log 
error  log 

Slave  servers  write  the  following  logs: 

{ domain . name } SRV-N 
referrer  log  SRV-N 
access  log  SRV-N 
error  log  SRV-N 

where  n is  slave  server  id:  1 , 2, ... 

The  /hsphere/ shared/ scripts/ cron/ cron-rotate  . pi  script  has  been 
adapted  to  calculate  statistics  on  load  balanced  cluster.  It  runs  on  master  and  slave 
servers  by  the  following  scheme: 

■ on  slave  servers  (e.g.,  1 :30am): 

■ synchronizes  logrotate  conf  files  on  master  and  slaves:  It  parses  log  rotate 
COnfigs  in  the  /hsphere /local/ conf  ig/httpd/ logrotate_conf  s/ 
directory  on  the  master  server.  They  point  to  the  user  logs  located  in  the 

/hsphere/local/home/<user>/logs/domain.  com/  directory.  On  master 
server,  log  filenames  look  like: 

{ domain . name } 
referrer  log 
access_log 
error  log 

Slave  servers  write  the  following  logs: 

{ domain . name } -SRV-N 
referrer  log-SRV-N 
access  log-SRV-N 
error  log  SRV-N 

where  N is  slave  server  id:  1, 2,  ...  cron-rotate.pl  merges  data  and  synchronizes 
respective  master  and  slave  logs. 

■ rotates  logs  on  slave  servers 

■ restarts  Apache 

■ on  master  server  (e.g.,  2:00am): 

■ rotates  logs  on  the  master 

■ restarts  Apache 

■ merges  master  and  slave  logs 

■ launches  log  analyzers  (Webalizer,  AWStats,  ModLogAn) 
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Load  Balanced  Cluster  Map 

The  following  two  files  construct  load  balanced  cluster  map.  At  the  moment,  they  need 
to  be  created  manually  on  master  and  slave  servers: 

■ /hsphere/local/config/lb.map  - created  on  the  master  server  and  has  the  following 
format: 

<Master_IP>  \ <Slave1_IP>  | . . . | <SlaveN_IP> 

The  lines  of  the  same  format  should  be  also  added  for  each  dedicated  IP  bound  on 
the  cluster: 

<Master_Dedicated_IP>  \ <Slave1_Dedicated_IP>  | . . . | <SlaveN_Dedicated_IP> 

■ /etc/hsphere/lb.id  - created  on  both  the  master  and  slave  servers  and  contains  the 
following  line: 

<CLUS TER_ TYPE>  \ <SERVER_ID> 

where  <CLUSTER_TYPE>  is  mail  or  web;  <SERVER_ID>  is  LB  server  id:  0 for  master,  1 
for  the  first  slave,  2 for  the  second  slave,  etc. 

For  example,  for  slave  server  with  <Slave2_IP>  in  LB  Web  cluster  the  lb. id  file  will 
look  like: 

web  | 2 

NAT  Configuration  for  Load  Balanced  Clusters 

To  configure  load  balanced  Web/mail  cluster  with  NAT,  you  must  have  NAT  turned  on 
(on  page  28)  in  Parallels  H-Sphere  and  put  external  Web/mail  server  IP  routed  by  the 
Load  Balancer  into  correspondence  with  the  master  server’s  internal  IP. 

For  example,  for  a load  balanced  Web  cluster  with  one  master  and  4 slave  servers, 
where  the  master  Web  server’s  internal  IP  192.168.0.100  corresponds  to  the 
external  IP  12.34. 56.100  bound  to  the  Load  Balancer. 

■ In  the  ~cpanel/shiva/psoft_config/ips-map.xml  file  on  the  CP  server  there  should  be 
the  following  record: 

<ips> 

<ip  ext="12 .34.56.100"  int="192 . 168 . 0 . 100"/> 

</ ips> 

■ All  dedicated  IPs  on  the  master  server  must  be  also  associated  with  corresponding 
IPs  on  the  Load  Balancer  and  similar  records  must  be  added  to  the  ip-map.xml  file: 

<ip  ext="LB  Dedicated  IP"  int="Master  Dedicated  IP"/> 

■ Also,  you  should  have  external  IP  in  the  E. Manager  ->  DNS  Manager  ->  Service  Zone 
menu  in  admin  CP.  For  example: 

www.test.com  3600  IN  A 12.34.56.100 
mail.test.com  3600  IN  MX  12.34.56.111 
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Load  Balancing  Support  in  Parallels  H- 
Sphere 

This  document  explains  functionality  of  the  scripts  that  enable  distribution  of  load 

balance  between  Apache  and  Virtual  FTP  servers. 

■ apache-confsynch.pl  accounts  for  synchronization  of  Apache  config  files  on  slave 
servers.  Amount  of  slave  servers  and  their  IDs  are  set  at  master  server  in  the 
/hsphere/local/ config/ slaves  . conf  file.  The  script,  also,  creates 
need_restart.txt  on  each  slave  to  mark  it  as  liable  to  restart. 

■ apache-need-restart.pl  runs  on  slave  servers,  checks  if  need_restart.txt  is 
available  there  and  marks  them  as  liable  to  restart.  In  other  words  this  script  servers 
as  a layer  between  LB  apache  restart  and  standard  apache-restart. 

■ apache-reconfig.pl  is  a modification  of  a standard  apache-reconfig  script/file(?) 
that  is  executed  on  slaves  and  is  only  different  from  it  in  that  it  sets  required  level  of 
restart  for  slaves  (either  gracefull  or  force). 

■ apache-repair.pl  is  a modification  of  a standard  apache-repair.pl  script  and  is  only 
different  in  that  it  sets  exclusive  lock  for  /etc/passwd,  /etc/shadow, 
/etc/groups  so  to  ensure  these  files  are  not  locked  by  rsync  and  so  a user  can 
be  started.  Otherwise,  all  files  will  be  marked  as  bad. 

■ ftp_anlz.pl  gathers  and  analyses  statistics 

■ ftp_anlz_user.pl  gathers  and  analyses  user  statistics. 

■ ftp-confsynch.pl  accounts  for  the  same  as  apache-confsynch.pl  on  Virtual  FTP 
severs. 

■ ftp-need-restart.pl  accounts  for  the  same  as  apache-need-restart.pl  on  Virtual  FTP 
severs. 

■ ftp-restart.pl  is  the  same  as  Apache,  but  for  Virtual  FTP 

■ master-ipsynch.pl  runs  on  a master  server  and  formats  data  for  slave  servers  so 
IPs  are  up  according  to  IP  mapping  set  in  the 

/hsphere/local/ conf  ig/map_table  . txt  file  on  each  slave. 

■ slave-ipupdate.pl  puts  up  IPs  formed  by  the  master-ipsynch . pi  script. 

As  of  now  Apache  and  Virtual  FTP  config  files  synchronization  is  executed  on  master 

server,  yet  it  is  expected  to  be  moved  onto  slave  servers. 


Installing  Load  Balanced  Web/Mail 
Clusters  in  Parallels  H-Sphere 

Load  balanced  cluster  solution  requires  3 or  more  physical  servers: 

■ Load  Balancer:  any  solution  like  Cytrix®  NetScaler 

(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314)  for 

load  balancing  across  the  web/mail  servers.  Load  Balancer  directs  traffic  to  another 
server  if  the  first  one  is  currently  overloaded. 
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■ NAS  (aka  Filer):  Server/client  shared  storage  solution  for  web/mail  content.  NAS 
may  be  installed  on  the  same  server  with  load  balancer  or  on  a separate  server. 
Also,  Web  and  mail  servers  can  jointly  use  one  NAS  or  have  their  own  NAS  one  for 
Web  and  one  for  mail.  In  this  documentation  we  consider  the  following  NAS’s: 

■ Generic  Linux  NFS 

■ NetApp  Filer  hardware 

■ FtedHat  GFS 

■ At  least  two  boxes  (master  and  slave)  for  web/mail  servers.  Load  balanced 
solution  implies  one  master  server  and  one  or  more  slave  servers. 

> To  create  Web/mail  load  balanced  clusters  integrated  into  Parallels  H- 
Sphere: 

1.  Install  and  configure  Load  Balancer  (on  page  301) 

2.  Prepare  NAS  (on  page  301) 

3.  Prepare  master  and  slave  Web/mail  boxes  (on  page  305) 

4.  Install  Parallels  H-Sphere  to  load  balanced  Web/mail  clusters  (on  page 
307) 


In  this  section: 


Step  1.  Install  and  Configure  Load  Balancer 301 

Step  2.  Prepare  NAS 301 

Step  3.  Prepare  Master  and  Slave  Web/Mail  Boxes 305 


Step  4.  Install  Parallels  Fl-Sphere  to  Load  Balanced  Parallels  H-Sphere  Clusters  307 


Step  1 . Install  and  Configure  Load  Balancer 

Purchase,  install  and  configure  load  balancer  solution  like  Cytrix®  NetScaler. 

Step  2.  Prepare  NAS 

Follow  procedures  below  for: 

■ NetApp  hardware  (on  page  300) 

■ Linux  NFS  shared  storage  (on  page  300) 

■ RedFlat  GFS  (on  page  300) 


In  this  section: 


NetApp  Flardware 302 

Generic  Linux  NFS 303 

RedFlat  GFS 304 
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NetApp  Hardware 

1.  Purchase  NetApp  NAS  from  www.netapp.com,  install  and  configure  the 
NAS  according  to  the  NetApp  Documentation 

(http://www.netapp.com/products/filer/).  Create  volumes/qtrees  on  the 
box  where  NetApp  NAS  is  to  be  installed. 

2.  Configure  your  NetApp  NAS  to  add  load  balanced  cluster  in  Parallels  H- 
Sphere  (read  the  NetApp  Manual  at 

http://ecserv1  .uwaterloo.ca/netapp/man/  for  commands): 

1.  Telnet  to  the  NetApp  NAS: 
telnet  <NASJP> 

Here,  <NASJP>  is  the  NetApp  NAS  IP. 

2.  Get  the  list  of  the  NAS  partitions  with  the  qtree  command: 

# qtree 

3.  To  enable  disk  quota  management,  export  the  /etc  directory  on  the  NetApp  NAS 
and  allow  to  mount  it  only  from  the  CP  box: 

# exportfs  -o  access=<CP_IP>,root=<CP_IP>,rw=<CP_IP>  /etc 

Here,  <CP_IP>  is  the  CP  server  IP. 

4.  To  enable  user  disk  space  management  on  the  web/mail  servers,  export  the 
user  storage  directory  on  the  NetApp  NAS  allow  to  mount  it  from  the  physical 
web/mail  boxes: 

# exportfs  -o 

access=<Master_IP>:<Slavel_IP>[ :<Slave2_IP>: . . . ] , root=<Master 
_IP>:<Slavel_IP>[ : . . . ] , rw=<Master_IP> :<Slavel_IP> [ : . . . ] 
<NAS_WebPath> 

Here,  <Master_IP> : <Slave1_IP>  [ : <Slave2JP> : . . . ] is  the  list  of  master  and  slave 
web/mail  server  IPs  separated  with  colon  (:),  <NAS_WebPath>  is  the  user  storage 
directory. 

5.  Exit  telnet  session  on  the  NetApp  NAS. 

3.  Prepare  NetApp  NAS  to  Work  With  Parallels  H-Sphere 

1 . Grant  rsh  access  to  the  NetApp  NAS  from  the  CP  box  to  root  and  cpanel  user. 

2.  Grant  nfs  access  to  the  /etc  directory  for  the  CP  box  in  rw  mode. 

3.  Grant  nfs  access  to  the  home  directory  on  the  storage  partition  (e.g., 
/vol/volO/home)  for  the  CP  box  in  rw  mode  with  root  privileges  (e.g.,  - 
access=1 92.1 68.0.9:1 92.1 68.0.1 0,  root=1 92.1 68.0.8:1 92.1 68.0.9:1 92.1 68.0.1 0). 

4.  On  CP  server,  set  the  QUOTA_MANAGER  property  in 
~cpanel/shiva/psoft_config/hsphere. properties  to  support  NetApp  quota 
manager  on  LB  cluster: 

QUOTA_MANAGER  = NET_APP 

More  about  external  quota  manager  support  in  Parallels  H-Sphere  (on  page  308). 


Load  Balancing  303 


Generic  Linux  NFS 

Important:  For  correct  load  balanced  cluster  implementation,  NFS  must  be  of  version 
3. 

1.  Login  as  root  to  a new  Linux  server  assigned  for  NAS  and  create  a 
separate  partition  for  shared  file  storage.  This  partition  must  be  on  a 
separate  hard  drive  on  a separate  controller  and  must  not  be  /var  or 
/ usr.  We  recommend  naming  it  /filer  to  avoid  possible  confusion. 

2.  Install/update  the  quota-3  . x package  from  the  following  location: 

# rpm  -Uvh 

http : //download. hsphere .parallels . com/ shiv/HS/<OSCODE>/ sysuti 
Is/ quota-3 . xx-x . 1386 . rpm 

where  <OSCODE>  is  a mnemonic  code  for  operating  system  supported  by  Parallels 
H-Sphere  (see  OSCODE  notation  in  Appendix  D of  Parallels  Pi-Sphere  Update 
Guide). 

Important:  The  quota  package  includes  NFS  support,  which  is  essential  for  load 
balanced  cluster  implementation.  Generic  quota  package  has  NFS  support  disabled 
by  default! 

3.  Add  the  “usrquota”  option  to  the  /filer  partition  in  /etc/fstab: 
LABEL=/filer  /filer  ext3  defaults , usrquota  1 1 

To  apply  changes,  run: 

# mount  -o  remount  /filer 

# quotacheck  -m  / filer 

# quotaon  / filer 

4.  On  the  /filer  partition,  create  directories  for  load  balanced  cluster 
file  storage: 

# mkdir  -p  / filer /<CLUSTER_TYPE>_<CLUSTER_ID> /hsphere 

where  <CLUSTER_TYPE>  is  web  or  mail,  and  <CLUSTER_ID>  is  a cluster  id  (there  may 
be  multiple  clusters  mounted  to  the  same  NAS). 

For  example,  for  the  first  Web  cluster  it  will  be  /fiier/web_Oi /hsphere. 

5.  Stop  all  services  except  ssh,  portmap,  and  nfs  related  services.  Check 
the  status  by  the  chkconfig  command: 

# chkconfig— list 

6.  To  enable  user  disk  space  management  on  the  web/mail  servers, 
export  the  user  storage  directory  on  the  generic  Linux  NAS.  For  this, 
add  the  following  lines  for  all  clusters  to  the  /etc/exports  file  on  the 
NAS  server: 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Master  IP> (rw, async, no  wdelay, insecure, no  root  squash) 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Slavel  IP> (rw, async, no  wdelay, insecure, no  root  squash) 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Slave2  IP> (rw, async, no  wdelay, insecure , no  root  squash) 


To  apply  changes,  run: 
# exportfs  -a 
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7.  Skip  this  step  for  mail  server  clusters. 

Edit  the  /etc/init . d/nf  s file.  Find  the  line  with  daemon  rpc.  rquotad  and  add 
the  -S  option  to  the  end  of  the  line,  like  this: 

daemon  rpc. rquotad  $RPCRQUOTADOPTS  -S 

After  that,  restart  NFS: 

# chkconfig— level  345  nfs  on 

# /etc/init .d/nf s restart 

Important:  NFS  configuration  on  the  NAS  may  differ  depending  on  the  hardware 
parameters,  the  number  of  clusters,  quota  and  load  on  the  servers.  To  properly 
configure  NAS  please  refer  to  the  following  guides: 

https://www.redhat.eom/f/pdf/rhel4/NFSv4WP.pdf 

http://www.citi.umich.edu/projects/nfs-perf/results/cel/dnlc.html 

http://www.oreillv.com/cataloq/nfs2/chapter/ch15.html 


RedHat  GFS 

> To  prepare  NAS  for  RedHat  GFS  filer 
(http: //www.  red  hat  com/software/rha/cifs /): 

1.  Install  and  configure  RedHat  GFS  cluster  on  a filer  according  to  the 
following  documentation: 

http://www.redhat.com/docs/manuals/csqfs/browse/rh-qfs-en/index.html 

http://www.redhat.com/docs/manuals/csqfs/browse/rh-cs-en/index.html 

http://www.tldp.org/HOWTO/LVM-HOWTO/index.html 

2.  Setup  GFS  file  system  type  on  a logical  volume  on  the  filer,  like  this: 

# gfs_mkfs  -p  lock_type  -t  cluster_name : gnbd_device  -j  2 
/ dev/ vg_name/ lv_name 

where  iock_type  is  a GFS  locking  type,  ciuster_name  is  a GFS  cluster  name, 
gnbd_device  is  a GNBD  device  name,  vg_name  is  a volume  group  name,  and 
iv_name  is  a logical  volume  name.  Further  on  in  the  document  we  will  use  the 
following  example: 

# gfs_mkfs  -p  lock_dlm  -t  alpha_cluster : gf si  -j  2 
/dev/vgOl/lvOl 

3.  Start  GNBD  server: 

# gnbd_serv 

Upon  successful  start,  you’ll  get  the  following  output: 

gnbd_serv:  startup  succeeded 

4.  Export  logical  volume  with  GFS  file  system: 

# gnbd_export  -d  /dev/vgOl/lvOl  -e  gfsl 
You  should  get  the  following  output: 

gnbd  clusterd:  connected 

gnbd  export:  created  GNBD  gfsl  serving  file  /dev/vgOl/lvOl 


Load  Balancing  305 


Step  3.  Prepare  Master  and  Slave  Web/Mail  Boxes 

Before  you  install  Parallels  H-Sphere  packages  to  master  and  slave  servers,  please 
make  sure  to  meet  the  following  requirements  for  correct  load  balancing: 

■ All  boxes  in  LB  cluster  must  have  the  same  OS  version  installed  on.  For  RedPlat 
GFS,  all  servers  must  be  RedPlat  servers.  In  case  of  generic  Linux  NFS  or  NetApp, 
master/slave  servers  under  FreeBSD  are  supported  in  FIS  3.0  RC  4 and  up. 

■ The  /hsphere  directory  on  a Web  server  should  not  be  created  a separate 
partition! 

The  operations  on  master  and  slave  servers  are  made  under  root. 

1.  Create  the  /hsphere  directory  on  the  master  and  all  slave  servers: 

# mkdir  /hsphere 

2.  If  you  are  using  GFS,  run  on  each  master  and  slave  servers: 

1.  Load  kernel  module: 

# modprobe  gnbd 

2.  Import  GFS  file  system  from  the  NAS  server: 

# gnbd_import  -i  FILER_NAME 

where  filer_name  is  the  NAS  server  domain  name.  You  should  get  the 
following  output: 

gnbd  import:  created  gnbd  device  gfsl 

gnbd  monitor:  gnbd  monitor  started.  Monitoring  device  #0 
gnbd  recvd:  gnbd  recvd  started 

3.  Mount  the  storage  directory  on  the  NAS  server  to  /hsphere  directory  on 
the  master  and  all  slave  servers. 

a For  RedHat  GFS: 

Add  the  following  mountpoint  to  /etc/fstab  on  the  master  and  all  slave  servers: 
/dev/gnbd/gf si  /hsphere  gfs  defaults  0 0 

Mount  the  GFS  logical  volume  on  the  master  and  all  slave  servers: 

# mount  -t  gfs  /dev/gnbd/gf si  /hsphere 
b For  generic  Linux  NFS  or  NetApp: 

Add  the  following  mountpoint  to  /etc/fstab  on  the  master  and  all  slave 
servers: 

<NAS_IP> : / filer  /<CLUS TER_ TYPE>  < CLUS TER_ID> / h sphe  re  /hsphere  nfs 
defaults , nfsvers=3 , rsize=327 68 , wsize=327 68  0 0 

For  mail  server  cluster,  also  add  these  mountpoints  on  all  servers: 

<NAS_IP> :/  filer/  <CLUSTER_TYPE>  <CLUSTER_ID>/ users  / var/  qmail /users 
nfs  defaults , nfsvers=3  0 0 

<NASJP> : / filer /<CLUSTER_TYPE>  <CLUSTER_ID>  / control 
/var/qmail/control  nfs  defaults , nfsvers=3  0 0 

To  mount  the  directory,  run: 

# mount  -a  &&  mount 

4.  On  the  master  server,  create  the  /hsphere/local/conf ig/lb .map 
file  of  the  following  format: 

<Master_IP>  \ <Slave1_IP>  | . . . | <SlaveN_IP> 
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Note:  The  lines  of  the  same  format  should  be  also  added  for  each  dedicated  IP 
bound  on  the  cluster: 

<Master_Dedicated_IP> \<Slave1_Dedicated_IP>  \ . . .\<SlaveN_Dedicated_IP> 

5.  On  every  master  and  slave  server,  create  the  /etc/hsphere/ib . id 

file  with  the  line  of  the  following  format: 

<CLUSTER_TYPE>  \ <SERVER_ID> 

where  <CLUSTER_TYPE>  is  mail  or  web;  <SERVER_ID>  is  LB  server  id:  0 for  master,  1 
for  the  first  slave,  2 for  the  second  slave,  etc. 

For  example,  for  slave  server  with  <Slave2_IP>  in  LB  Web  cluster  the  lb. id  file  will 
look  like: 

web  | 2 

6.  Generate  SSH  keys  to  access  the  master’s  root  from  each  slave  server 
without  password. 

1 . Log  into  each  slave  server  as  root. 

2.  Create  public  key  on  each  slave  server: 

# ssh-keygen  -t  dsa 

3.  Log  from  each  slave  server  to  the  master  server  as  root  and  insert  the  contents 
of  the  /root/.  ssh/id_dsa.  pub  file  from  each  slave  server  into  the 

/root/ . ssh/authorized  keys2  file  of  the  master  server. 

4.  Log  from  the  each  slave  server  into  the  master  server  as  root  once  again  to 
ensure  slave  servers  are  able  to  log  into  the  master  without  password: 

# ssh  root@<Master_IP> 

Answer  yes  to  all  prompts.  This  will  add  the  master  server  to  the  list  of  known 
hosts  (/root/ . ssh/known_hosts)  of  a slave  server.  After  that,  load 
balancing  synchronization  scripts  will  work  without  password  prompts. 

7.  Important:  To  make  sure  Parallels  H-Sphere  related  data  is  correctly 
synchronized  on  master  and  slave  servers,  add  time  synchronization 
(on  page  32)  to  the  master  and  slave  servers’  crontabs. 
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Step  4.  Install  Parallels  H-Sphere  to  Load  Balanced 
Parallels  H-Sphere  Clusters 

1.  Log  into  Parallels  H-Sphere  admin  CP  (it  is  assumed  you  have  Parallels 
H-Sphere  3.0  and  up  already  installed). 

2.  Add  master  and  all  slave  servers  as  physical  servers  to  Parallels  H- 
Sphere. 

3.  Set  master-slave  relations  between  master  and  slave  physical  servers. 
This  is  described  in  the  section  Load  Balanced  Server  Clusters  of 
Parallels  H-Sphere  Service  Administrator  Guide. 

4.  Add  Web/mail  logical  server  only  to  master  physical  server.  Do  not 

add  logical  servers  to  slave  servers! 

In  logical  server  options  you  need  to  set  Load  Balancer  Server  Parameters: 

■ File  Server  Type:  file  storage  OS  type  (on  page  292),  like  UNIX  for  generic 
Linux  NFS 

■ File  Server:  file  storage  volume  location,  like 

<NAS_IP>:  / £ Her  / <CLUSTER  TYPE>  <CLUSTER  ID> / in  the  above  example 

■ File  Path:  (optional)  file  storage  path  to  Parallels  H-Sphere  installation  directory, 
like  /f  iler /<CLUSTER_TYPE>  <CLUSTER_ID> /hsphere  in  the  above  example 

■ File  server  Volume  ID:  file  storage  volume  ID,  like 
<CLUSTER_TYPE>  <CLUSTER_ID>  in  the  above  example. 

5.  For  mail  LB  cluster,  it  is  required  to  configure  Horde  Webmail  frontend 
(on  page  137)  to  use  external  Web  server  and  external  MySQL 
database  server,  and  also  to  configure  SpamAssassin  (on  page  162)  to 
external  MySQL  database. 

6.  Configure  NAT  for  LB  Web/mail  clusters 

Parallels  H-Sphere  Control  Panel  works  with  only  one  logical  server  (that  is,  master 
server)  for  each  load  balanced  Web  cluster.  To  configure  load  balanced  Web/mail 
cluster  with  NAT,  you  must  have  NAT  turned  on  (on  page  28)  in  Parallels  H-Sphere 
and  put  external  Web/mail  server  IP  routed  by  the  Load  Balancer  into 
correspondence  with  the  master  server’s  internal  IP. 

For  example,  for  a load  balanced  Web  cluster  with  one  master  and  4 slave  servers, 
where  the  master  Web  server’s  internal  IP  192.168.0.100  corresponds  to  the 
external  IP  12. 34. 56.100  bound  to  the  Load  Balancer. 

■ In  the  '-cpanei/shiva/psoft  config/ips-map . xml  file  on  the  CP  server 
there  should  be  the  following  record: 

<ips> 

<ip  ext="12 .34.56.100"  int="192 . 168 . 0 . 100"/> 

</ ips> 

■ All  dedicated  IPs  on  the  master  server  must  be  also  associated  with 
corresponding  IPs  on  the  Load  Balancer  and  similar  records  must  be  added  to 
the  ip-map. xml  file: 

<ip  ext="LB  Dedicated  IP"  int="Master  Dedicated  IP"/> 
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■ Also,  you  should  have  external  IP  in  the  E. Manager  ->  DNS  Manager  ->  Service  Zone 
menu  in  admin  CP.  For  example: 

www.test.com  3600  IN  A 12.34.56.100 
mail.test.com  3600  IN  MX  12.34.56.111 

7.  Download  the  latest  Parallels  H-Sphere  updater  of  Parallels  H-Sphere 
3.0  RC  1 and  up  and  follow  the  instructions  on  adding  new  servers  into 
Parallels  H-Sphere  to  install  Parallels  H-Sphere  related  packages  only 
on  master  server. 

8.  In  the  updater’s  command  line,  run  one  of  the  following  commands  to 
complete  installation  and  configuration  on  slave  servers: 

hspackages  slaves=web 
hspackages  slaves=mail 
hspackages  slaves=all 

More  about  updater  options  read  in  Parallels  H-Sphere  Update  Guide. 


Quota  Managers 

Parallels  H-Sphere  supports  quota  management  for  third  party  file  storage  systems  like 
BlueArc  or  NetApp  for  load  balanced  Web/mail  clusters  (on  page  292).  If  not  specified 
otherwise,  Parallels  H-Sphere  uses  generic  Linux/FreeBSD  server  quota  manager. 

To  set  a third  party  NAS  quota  manager,  add  the  quota_manager  variable  in 

~cpanel/ shiva /pso ft  conf ig/hsphere  .properties,  for  example,  like  this: 

QUOTA_MANAGER  = BLUE_ARC 

The  following  quota  managers  are  supported: 

■ UNIX  - generic  Linux/FreeBSD  quota  manager  (default) 

■ NET_APP  - NetApp  quota  manager  (http://www.netapp.com/products/filer/) 

■ BLUE_ARC  - BlueArc  quota  manager  (http://www.bluearc.com/) 

■ EMC_CELERRA  - EMC  Celerra  quota  manager 
(http://www.emc.com/products/networking/servers/index.isp) 
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Resources  Migration 


This  chapter  explains  how  to  migrate  resources  into  Parallels  H-Sphere  from  Parallels 
H-Sphere  and  other  control  panels  using  XML-structured  data.  It  can  also  serve  as  a 
guide  to  setting  up  a large  number  of  Parallels  H-  Sphere  users  at  a time.  You  are 
expected  to  have  an  installed  and  configured  Parallels  H-Sphere  control  panel  on  the 
target  server. 

Migratable  Resources 

Users  can  be  migrated  with  the  following  resources: 

■ User  contact  and  billing  info 

■ Domains  (with  or  without  DNS) 

■ DNS:  custom  A,  MX,  CNAME  records;  domain  vhost  aliases;  domain  aliases  with 
their  DNS  and  mail  configuration 

■ Web:  settings,  FrontPage,  CGI,  CGIDir,  MIME,  PHP,  SSI,  ErrorDoc,  ErrorLog, 
TransferLog,  Webalizer,  ModLogAn,  RefferrerLog,  AgentLog,  Vhost  alias,  Directory 
indexes,  Redirect,  Urchin3,  Urchin4,  ASP,  ASP.NET,  ColdFusion,  MSSQLManager 

■ Mail:  Mailboxes,  Autoresponder  for  mailboxes,  Mailforwards,  Mailing  lists 

■ FTP:  resources:  virtual  hosts,  anonymous  virtual  hosts,  virtual  host  directories  with 
permissions,  virtual  host  users,  FTP  subaccounts  (Unix) 

■ MySQL:  users,  databases  with  user  permissions 

■ PostgreSQL:  users,  databases 

■ MSSQL:  users,  logins,  databases 

■ ODBC:  dsn  records  with  params 

Crontab:  crontab  records  for  users  The  following  resources  are  NOT  YET  implemented 
in  XML  migration  mechanism: 

■ DNS:  instant  access  domain  alias 

■ Web:  SSL,  Shared  SSL,  MivaEmpresa,  MivaCart,  osCommerce,  PhpBB 


In  this  chapter: 

Migration  Procedure 
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Migration  Procedure 

The  migration  procedure  takes  the  steps  below. 


In  this  section: 


Step  1.  Create  XML  File  Containing  User  Data 310 

Step  2.  Create  XML  File  Containing  Reseller  Plan  Data 316 

Step  3.  Prepare  The  Target  Control  Panel 321 

Step  4.  Create  Reseller  Plans 322 

Step  5.  Create  Resellers 322 

Step  6.  Create  End  Users 322 

Troubleshooting 323 


Step  1 . Create  XML  File  Containing  User  Data 

Create  xml  and  dtd  files  to  migrate  resellers  and  end  users  or  end  users  without 
resellers. 

If  you  are  moving  users  from  Parallels  H-Sphere,  do  it  with  the  UserlnfoExtractor  utility 
as  suggested  in  Creating  User  Migration  XMLs  in  Parallels  H-Sphere  (on  page  311). 

If  you  are  moving  users  from  a different  control  panel,  follow  the  instruction  on  Creating 
User  Migration  XMLs  Outside  Parallels  Pi-Sphere  (on  page  315). 

In  this  section: 


Creating  User  Migration  XMLs  in  Parallels  H-Sphere 31 1 

Creating  User  Migration  XMLs  Outside  Parallels  H-Sphere 315 
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Creating  User  Migration  XMLs  in  Parallels  H-Sphere 

This  document  explains  how  to  create  XML  files  with  Parallels  H-Sphere  reseller  and 
end  user  data  for  migration  to  a different  Parallels  H-Sphere  cluster. 

User  info  can  be  obtained  and  formatted  with  the  UsersinfoExtractor  utility 
executed  under  Control  Panel  user  (on  page  53). 

UsersinfoExtractor  extracts  resellers  into  the  migrate  resellers  . xml,  and 

their  end  users  separately  into  migrate_users  .xml. 

UsersinfoExtractor  runs  with  the  following  parameters: 

■ -resellers  - extracts  only  resellers  into  the  migrate_resellers.xml  file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  OPTIONS 

where  options  include: 

■ -reseiiersbynames  - extract  listed  resellers: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -reseiiersbynames  <RESELLER-1>  . . . <RESELLER-N> 

■ -reseiiersf  romf  ile  - extract  resellers  listed  in  a plain  text  file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -reseiiersf romf ile  /home/resellers . txt 

■ -usersbynames  - extract  resellers  for  listed  individual  users: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersbynames  <USERNAME-1>  . . . <USERNAME-N> 

• -usersfromfile  - extract  resellers  for  individual  users  listed  in  a plain  text 
file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersfromfile  /home/users . txt 

■ -use rsbyl server  - extract  resellers  for  all  users  located  on  a specified  logical 
server: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersbylserver  <LSERVER_ID> 

• -users  - extracts  end  users  into  the  migrate_users . xml  file.  This  option  is 
meant  by  default  if  both  -resellers  and  -users  options  are  omitted  in  the 
command: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  [- 
users]  OPTIONS 

where  options  include: 

■ -usersbynames  - extract  listed  end  users  by  usernames: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
users  -usersbynames  <USERNAME-1>  . . . <USERNAME-N> 

■ -usersfromfile  - extract  users  by  usernames  listed  in  a plain  text  file: 
java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
users  -usersfromfile  /home/users . txt 

■ -reseiiersbynames  - extract  users  that  belong  to  listed  resellers: 
java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
users  -reseiiersbynames  <RESELLER-1>  . . . <RESELLER-N> 
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■ -reseiiersf  romf  ile  - extract  users  that  belong  to  resellers  listed  in  a plain 
text  file: 

java  psof t.hsphere. migrator . UsersInfoExtractor  [-force]  - 
users  -reseiiersf romf ile  /home/resellers . txt 

■ -use rsbyl server  - extract  users  located  on  a certain  logical  server: 
java  psof t.hsphere. migrator .UsersInfoExtractor  [-force]  - 
users  -usersbylserver  <LSERVER_ID> 

Use  the  force  parameter  to  ignore  errors.  Error  messages  will  be  written  to 

migrate  errors.log. 


Important:  Note  that  you  must  specify  user  and  reseller  names,  not  ids! 

Important:  If  you  are  migrating  master  admin’s  end  users,  you  just  extract  them  into 
migrate_users . xml  without  extracting  master  admin  as  reseller. 

See  also: 

■ Sample  XML  file  with  reseller  data: 

http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  resellers  25.xml 

■ Sample  XML  file  with  end  user  data: 
http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  users  25.xml 

■ Sample  DTD  file  for  resellers: 
http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd 

■ DTD  file  for  end  users:  /hsphere/local/home/cpanel/hsphere/WEB- 
INF/classes/psoft/hsphere/migrator/users.dtd. 

In  this  section: 


DTD  Structure  of  Reseller  XML  Migration  File 
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DTD  Structure  of  Reseller  XML  Migration  File 

Data  Type  Definitions 

Here  is  the  DTD  structure  defined  in  resellers. dtd: 

<?xml  version=”1 .0”  encoding=”UTF-8”?> 

<!ELEMENT  resellers  (reseller*,  users?)> 

<!ELEMENT  reseller  (info+, administrator, zone*, users?)> 
<!ELEMENT  zone  (instantalias*)> 

<!ELEMENT  instantalias  (#PCDATA)> 

<!ELEMENT  administrator  (#PCDATA)> 

<!  ATT  LI  ST  reseller  login  CDATA  #REQUIRED> 

<!  ATT  LI  ST  reseller  password  CDATA  #REQUIRED> 

<!  ATT  LI  ST  reseller  plan  CDATA  #REQUIRED> 

<!ATTLIST  administrator  login  CDATA  #REQUIRED> 
<!ATTLIST  administrator  password  CDATA  #REQUIRED> 
<!ATTLIST  administrator  email  CDATA  #REQUIRED> 

<!  ATT  LI  ST  zone  name  CDATA  #REQUIRED> 

<!  ATT  LI  ST  zone  email  CDATA  #REQUIRED> 

<!ATTLIST  instantalias  prefix  CDATA  #REQUIRED> 
<!ATTLIST  instantalias  tag  CDATA  #REQUIRED> 

<!ENTITY  % users_rules  SYSTEM  “users. dtd”>  %users_rules; 


DTD  Chart 

The  above  structure  may  be  represented  graphically  in  the  following  chart: 

resellers 

/ ... 

reseller 


/ 

/ 

/ / \ 

/ / \ 
info  / \ 

| administrator  zone 

item  instantalias 


Attributes  Description 

■ reseller: 

■ login  - reseller  login 
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■ password  - reseller  password 

■ plan  - the  plan  the  reseller  is  signed  up  for 

■ info  (contact/billing  signup  information):  (see  signup  fields  description  in  the  section 
User  Signup  Customization  of  Parallels  H-Sphere  Customization  Guide) 

■ type=”_ci_”  (contact  info)  or  type=”_bi_”  (billing  info) 

■ administrator: 

■ login  - reseller  admin  cp  login 

■ password  - reseller  admin  cp  password 

■ email  - reseller  admin  email  address 

■ zone: 

■ name  - the  name  of  the  reseller  service  zone 

■ email  - email  for  the  reseller  service  zone  (for  example,  if  it  is 
reseller@example.com,  it  must  be  set  as  reseller . example . com) 

■ instantalias: 

■ prefix  - prefix  to  be  added  to  instant  aliases  for  this  zone  (for  example,  u) 

■ tag  - shared  IP  tag  for  the  instant  alias  (usually,  2) 

XML  example  with  reseller  data: 

http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  resellers  25.xml 
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Creating  User  Migration  XMLs  Outside  Parallels  H-Sphere 

This  section  explains  how  to  format  user  data  for  migration  from  third  party  hosting 
systems  into  Parallels  H-Sphere.  Use  it  to: 

■ migrate  direct  end  users,  resellers,  and  resellers’  end  users; 

■ migrate  only  direct  end  users  if  you  don’t  have  resellers. 


Files 

Create  the  following  files: 

■ resellers.dtd  - data  type  definitions  for  resellers 

■ example:  http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd 

■ explanation  (on  page  313) 

■ users.dtd  - data  type  definitions  for  end  users 

■ example:  http://hsphere.parallels.com/HSdocumentation/xmls/users.dtd 

■ explanation:  http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ 

■ migrate_resellers.xml  - XML  file  containing  reseller  data  only 

■ example: 

http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  resellers  25.xml 

■ explanation  (on  page  313) 

■ migrate_users.xml  - XML  file  containing  user  data  only 

■ example: 

http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  users  25.xml 

■ explanation:  http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ 

You  may  have  data  for  hundreds  and  thousands  of  users  in  the  xml  file. 

Alternatively,  you  may  set  DTD  definitions  directly  within  the  XML  file: 

<?xml  version=”1 .0”  encoding=”utf-8”?> 

<!DOCTYPE  users  [ 

//  DTD  rules  as  in  users.dtd 

]> 

<users> 

We  recommend  defining  DTD  externally,  using  our  latest  DTD: 

ciDOCTYPE  users  SYSTEM  “users.dtd”> 
ciDOCTYPE  resellers  SYSTEM  “resellers.dtd”> 

DTD  files  help  ensure  that  all  XMLs  are  formatted  the  right  way.  But  please  note  that 
XML  files  will  be  created  no  matter  DTD  file  exists  or  not. 

Warning:  If  you  make  a mistake  in  DTD  definitions,  migration  may  fail. 

XML  Validation 

Once  you  have  created  the  XML,  please  do  the  following: 

1 . Validate  the  user  data  xml  files  with  any  xml  validation  software. 
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2.  Make  sure  the  xml  file  does  not  contain  user  with  the  login  “admin”. 

3.  Make  sure  that  mail  sections  of  each  user  don’t  contain  mail  loops. 

4.  Ensure  that  the  billing  period  starting  date  has  the  MM/DD/YY  format. 

5.  Make  sure  that  in  the  user  tag  the  value  of  the  login  attribute  is  unique  and  doesn’t 
begin  with  a number  (this  value  will  be  used  as  the  Parallels  H-Sphere  control  panel 
login  name). 

Now  you  are  ready  to  create  the  accounts. 

Step  2.  Create  XML  File  Containing  Reseller  Plan  Data 

Note:  Skip  this  step  if  you  are  migrating  only  master  admin’s  end  users. 

Create  XML  files  for  the  reseller  plans  to  be  migrated.  If  you  migrate  from  Parallels  hl- 
Sphere,  use  the  PianExtractor  utility.  Otherwise,  create  plan  XML  according  to  our 
documentation.  Please  refer  to  Migrating  Plans  with  XML  (on  page  317)  for  details. 

In  this  section: 

Migrating  Plans  with  XML 317 
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Migrating  Plans  with  XML 

Plan  settings  are  stored  in  XML  format,  which  allows  extracting  and  moving  them  to 
other  locations. 

Migratable  Plans.  Migratable  plans  include  all  non-reseller  plans,  namely:  Unix, 
Windows,  Admin,  MySQL,  E-Mail,  Unix  Real  Server,  Windows  Real  Media.  All  end  user 
plans,  including  those  of  master  admin  and  resellers,  are  migratable. 

Migration  Tools.  Plans  are  migrated  with  two  Java  classes,  PianExtractor  and 
PlanCreator,  located  in  the  ~cpanel/shiva/psoft/hsphere/migrator/ 

directory. 

1 ) PianExtractor  is  a Java  utility  to  extract  Parallels  H-Sphere  plans  into  XML  format. 
Extracted  plans  are  stored  in  the  plans  .xml  file. 

2)  PlanCreator  is  a tool  for  importing  plans  to  a new  CP  from  the  file  plans . xml  with 
plans  extracted  by  PianExtractor. 

Also,  you’ll  need  to  place  the  following  files  in  the 

~cpanel/ shiva/psof t/hsphere/migrator/  directory: 

■ plans.xml  (http://hsphere.parallels.com/HSdocumentation/xmls/plans.xml)  - XML- 
formatted  information  about  plans  extracted  by  PianExtractor. 

■ plans.dtd  (http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd)  - DTD 
scheme  for  plans . xml. 

■ migrate_pians . log  - messages  about  errors  occurred  during  plan  extraction. 


In  this  section: 


Plan  Extractor 318 

Plan  Creator 318 

XML  Document  Structure 319 

XML  Elements  and  Attributes 320 
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Plan  Extractor 

Log  into  CP  server  as  cpanel  (on  page  53)  and  run  PianExtractor: 

java  psoft . hsphere . migrator . PianExtractor  [-force]  -resellername 
res_name  [-plans  the  list  of  plan  names ] [-ids  the  list  of  plan  ids] 

Options: 

- The  -force  option  is  used  to  ignore  all  possible  errors  while  extracting  plans. 

- The  -resellername  option  requires  the  username  of  the  reseller  whose  plans  are 
extracted.  To  extract  plans  for  master  admin,  use  option  -resellername  admin. 

■ The  -plans  option  requires  names  of  plans  to  be  extracted  for  this  reseller.  If  a 
plan  name  contains  spaces,  it  must  be  quoted,  e.g.: 

• plans  Unixl  'Reseller  2'  WinBest33 

If  you  omit  both  -plans  and  -ids,  all  plans  will  be  extracted. 

■ The  -ids  option  requires  IDs  of  plans  to  be  extracted  for  this  reseller.  If  you  omit 
both  -plans  and  -ids,  all  plans  will  be  extracted. 

Examples: 

java  psoft.hsphere.migrator.PlanExtractor  -force  -resellername  RESELLER  -plans 
silver  ‘unix  gold’ 

java  psoft.hsphere.migrator.PlanExtractor  -force  -resellername  RESELLER  -ids  7564 
7675 

java  psoft.hsphere.migrator.PlanExtractor  -force  -resellername  RESELLER 
java  psoft.hsphere.migrator.PlanExtractor  -resellername  admin  -plans  silver  - 
resellername  RESELLER  -ids  7564 

PianExtractor  writes  error  messages  to  migrate  plans  . log. 


Plan  Creator 

Run  PlanCreator  as  cpanel  with  the  following  syntax: 

java  psoft . hsphere . migrator . PlanCreator  [-active]  -d  plans. xml  [- 
createprices ] 

Options: 

■ -active  - if  possible,  activate  plans  after  they  are  created. 

■ -d  plans. xml  - specify  plan  XML  file  to  be  taken. 

■ -createprices  - create  prices  for  plans. 

Make  sure  to  restart  Parallels  H-Sphere  (on  page  41)  after  running  PlanCreator. 
PlanCreator  writes  error  messages  to  migrate_plans  . log. 
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XML  Document  Structure 


The  structure  of  plans  .xml  looks  as  follows: 

plans 


plan 


/ 


/\ 


/ I 

periods  options 

/ ...  | ... 

/\ 

period 
\ 


/ I \ 


/ I \ 


LogicalGroup 
/ I 

/ I 

/ I 


\ 


resource 


customparam  postparam  param 
LogicalGroup 


if resource 


/ 


\ 


ifgroup 


/ 


\ 


resource  ifgroup  resource 


/ I \ 

special  fields  price... 


I 

special 


resource 


\ 

LogicalGroup 


Example  of  plans. xml:  http://hsDhere.parallels.com/HSdocumentation/xmls/plans.xml 
DTD  Scheme:  http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd 
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XML  Elements  and  Attributes 

1.  plan  - plan  description: 

■ name  - plan  name 

■ reseller  - reseller  name  (if  not  available,  admin  is  assumed) 

■ wizard  - wizard  name 

2.  period  - plan  periods: 

■ id  - period  id 

■ size  - period  duration 

■ type  - period  type  (DAY,  WEEK,  MONTH,  YEAR) 

■ discountusage  - usage  discount  (%) 

■ discountsetup  - setup  discount  (%) 

■ discountunit  - recurrent  discount  (%) 

3.  param  - plan  parameters  used  for  the  plan  creation: 

■ name  - parameter  name 

value  - parameter  value  Parameters: 

■ trial  - billing  type:  0 - Without  billing,  1 - Paid,  2 - Trial 

■ triai  duration  - trial  period  for  the  billing  type  trial 

■ trial  credit  - credit  limit  for  the  billing  type  trial 

■ hard  credit  - Credit  limit 

■ send_invoice  - enable  e-mail  invoice  notification 

■ mixedip  - default  IP  type  (shared  or  dedicated) 

■ shared_ip_tag  - shared  IP  Tag 

■ caiias  - instant  alias  for  the  given  shared  IP  tag 

■ stopgapaiias  - stopgap  domain  for  the  given  shared  IP  tag 

■ money_back  - enable  money  back 

■ money_back_days  - money  back  guarantee  in  days 

■ periods  - the  number  of  plan  periods 

4.  postparam  - parameters  to  be  set  after  the  plan  creation: 

■ name  - parameter  name 

value  - parameter  value  Parameters: 

■ contactinfo  - enable  contact  info 

■ biliinginf o - enable  billing  info 

■ _tempiate  - default  template 

■ _templates_dir  - template  directory 

5.  customparam  - custom  parameters  to  be  set  after  the  plan  creation: 

■ name  - parameter  name 

■ value  - parameter  value 

6.  resource  - resources  available  for  the  plan. 
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Check  corresponding  plan  wizard  XML  documents  in  the 

'-cpanei/psoft/hsphere/pian/wizard/xmi/  directory  for  the  list  of  available 
resources  and  the  way  they  are  set: 

■ name  - resource  name 

■ enable  - is  resource  enabled 

■ include  - is  resource  included 

■ active  - is  resource  activated 

7.  price  - resource  price: 

■ id  - price  id 

■ freeunits  - free  units 

■ setup  - setup  units 

■ unit  - monthly  units 

■ usage  - extra  units 

8.  LogicalGroup  - the  plan’s  logical  group: 

■ name  - logical  group  name 

■ type  - logical  group  type 

■ groupid  - logical  group  id 

9.  special  - special  resource  parameters: 

■ name  - special  field  name 

■ value  - special  field  value 


Step  3.  Prepare  The  Target  Control  Panel 

Before  you  start  creating  accounts  from  the  xml  files,  log  as  cpanel  user  (on  page  53), 

go  to  the  target  Parallels  H-Sphere  control  panel  and  do  the  following: 

1.  Make  sure  that  the  names  of  the  plans  are  exactly  the  same  as  those  in 
your  user  data  xml  file.  To  get  a list  of  all  reseller  and  user  plans  in  the 
system,  run: 

java  psof t.hsphere. migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -dl  -pp 

2.  In  the  xml  file,  find  users  that  have  empty  or  filled  mysql  tag.  In  the 
control  panel,  enable  MySQL  resource  for  the  plans  you  are  migrating 
these  users  to. 

3.  If  you  intend  to  migrate  the  existent  user  content  into  Parallels  H- 
Sphere,  include  but  deactivate  FrontPage  in  all  plans  you  are  migrating 
your  customers  to,  and  in  which  FrontPage  will  be  used. 

4.  If  you  want  to  preserve  original  billing  period  start  date,  make  sure  that 
the  billing  periods  have  the  same  duration  and  go  in  the  same  order  as 
those  in  your  old  control  panel. 
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Step  4.  Create  Reseller  Plans 

Note:  Skip  this  step  if  you  don’t  have  resellers. 

If  you  have  resellers,  run  PlanCreator  to  create  reseller  plans  on  the  target  Parallels  H- 
Sphere  installation,  for  example: 

java  psoft . hsphere . migrator . PlanCreator  -active  -d  plans. xml 

Please  refer  to  Migrating  Plans  with  XML  (on  page  317)  for  details. 

Step  5.  Create  Resellers 

To  create  resellers,  run  ResellerUserCreator: 

java  psoft . hsphere . migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -1  migrate.log  -dl 

Step  6.  Create  End  Users 

To  migrate  end  users,  run  CommonUserCreator: 

java  psoft . hsphere . migrator . CommonUserCreator  -d  migrate_users . xml  -1 
migrate . log  -dl 


Note:  To  prevent  double  charges  for  resources  billed  on  the  monthly  basis,  such  as 
Traffic  and  Disk  Usage,  CommonUserCreator  shifts  start  date  for  them  to  the  day 
before  the  date  of  migration. 
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Troubleshooting 

If  the  migration  software  fails  to  create  a reseller/end  user  account,  it  will  return  an  error 
and  stop  the  migration.  In  this  case,  read  the  messages  on  the  screen  to  find  which 
user  caused  the  failure,  read  the  log  file  and  try  to  remove  the  cause  of  the  error. 

Note:  If  the  domain  tag  of  this  user  in  the  XML  file  contains  the  ip  attribute  and  if  the  IP 
in  this  user’s  domain  was  created  before  the  error  occurred,  go  to  the  Parallels  hl- 
Sphere  control  panel  and  delete  this  IP. 

Then,  proceed  with  the  migration  using  the  above  command  plus  one  of  these  two 
options: 

■ -r  userjogin  - proceed  with  the  migration  starting  with  the  user  with  this  login 
name; 

■ -rc  userjogin  - delete  this  user  and  then  proceed  with  the  migration  starting  with 
this  user. 

The  full  command  must  look  like  this: 

a)  for  a reseller’s  end  user: 

java  psoft . hsphere . migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -1  migrate.log  -dl  -r  user_login 

b)  fora  direct  end  user: 

java  psoft . hsphere . migrator . CommonUserCreator  -d  migrate_users . xml  -1 
migrate . log  -dl  -r  user_login 
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Backup  and  Recovery 


This  chapter  explains  how  to  back  up  Parallels  H-Sphere  system  and  user  data. 

Backup  of  the  Control  Panel  server  with  the  PostgreSQL  system  database  is  done  by 
the  Parallels  H-Sphere  backup  script.  It  requires  PostgreSQL  client  version  7.3  or 
higher  installed  and  the  psql  program  available  in  the  system  paths  on  the  CP  server. 

Backing  up  content  on  the  Unix  servers  is  performed  manually.  See  the  backup  and 
recovery  list  (on  page  326)  of  Parallels  H-Sphere  related  directories  and  files. 

We  recommend  that  you  set  up  a separate  server  to  store  backup  archives. 

In  this  chapter: 
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Parallels  H-Sphere  Backup  and  Recovery  List 326 

Recovering  Parallels  H-Sphere  Control  Panel 328 

Recovering  Unix  Hosted  Parallels  H-Sphere  Servers 330 

Restoring  Files  and  Directories  from  Backup 332 

Restoring  the  Parallels  H-Sphere  System  Database  From  Backup 332 

Fixing  Crashed  Parallels  H-Sphere  Database 336 

Backing  Up  Winbox 337 

Recovering  Winbox 339 

Recovering  Winbox  Quota 345 
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Backing  Up  Parallels  H-Sphere  Control 
Panel  Server 


This  section  explains  how  to  back  up  the  Control  Panel  server  with  the  system 
database  by  means  of  the  backup  script. 

The  backup  script  located  in  the  /hsphere/shared/backup  directory.  The  script 
includes  the  following  files: 

■ hs_bck  - the  main  script  file 

■ hs_bck.  cfg  - custom  configuration  file.  This  is  the  file  to  store  the  list  of 
directories  to  back  up. 

■ hs_bck.cfg.org  - default  configuration  file.  It  can  be  overwritten  with  Parallels  hl- 
Sphere  updates.  This  is  where  you  can  find  the  updated  list  of  parameters  to  the 
hs_bck  script  if  it  has  been  changed  in  a new  version. 

■ hs_bck . txt  - description/readme  file. 

You  need  to  configure  the  script  by  editing  the  hs_bck . cfg  file. 

> To  back  up  Parallels  H-Sphere  CP  server: 

1.  Log  into  the  CP  server  as  root: 

su  - 

2.  cd  into  the  backup  script  directory: 

cd  /hsphere/shared/backup 

3.  Make  sure  the  files  hs_bck . cfg  and  hs_bck . cfg . org  are  identical 
in  what  is  not  your  custom  settings.  The  format  of  the 

hs_bck . cf  g . org  file  may  change  with  Parallels  H-Sphere  updates, 
and  it  is  important  to  ensure  that  the  backup  script  is  launched  with 
correct  parameters. 

4.  In  hs_bck . cfg,  edit  the  list  of  directories  and  databases  to  back  up. 
See  the  backup  and  recovery  list  (on  page  326). 

5.  In  hs_bck . cfg,  edit  the  the  backup  storage  directory,  the  number  of 
latest  backups  to  be  stored  (7  by  default),  the  log  file,  etc. 

6.  Run  the  backup  script. 

■ For  regular  automatic  backups,  add  the  execution  of  the  hs_bck  file  into  the  CP 
server  crontab  configuration  (on  page  33),  e.g.: 

<TIME>  /hsphe  re/shared/backup/hs  bck  hs  bck.cfg  2>&1  > 

/ dev/ null 

For  example,  to  run  the  backup  script  every  day  at  6:13  AM,  add  the  following 
line: 

13  6 * * * /hsphere/shared/backup/hs  bck 
/hsphere/shared/backup/hs  bck.cfg  2>&1  > /dev/null 

■ For  additional  parameters  to  this  script,  please  run: 

/hsphere/ shared/backup/hs_bck 
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System  DB  Dump 

In  addition  to  backing  up  the  pgsqi  directory  on  the  CP  server,  the  backup  script  can 
also  create  a dump  of  Parallels  H-Sphere  system  database  and  Parallels  SiteStudio 
databases.  For  this,  make  sure  the  following  directories  are  listed: 

PROP_FILE  /hsphere/local/home/cpanel/shiva/psoft_config/hsphere. properties 

PROP_FILE 

/hsphere/ shared/ SiteS tudio/psof t_conf ig/ counter . properties 
PROP_FILE 

/hsphere/ shared/ S iteS tudio/psof t_conf ig/poll . properties 
PROP_FILE 

/hsphere/ shared/ SiteStudio/ psof t_conf ig/ guestbook . properties 

If  Parallels  Fl-Sphere  database  is  large,  the  dump  can  take  several  hours  to  complete. 
You  can  speed  it  up  by  setting  f sync=of  f 

in  postgresqi . conf . When  you  are  done,  unset  this  option  back  for  safety  reasons. 


Parallels  H-Sphere  Backup  and  Recovery 
List 


Following  is  the  list  of  directories  and  files  to  back  up  and  recover.  Backup  can  be  done 
by  means  of  the  Parallels  Fl-Sphere  backup  script  (on  page  325)  on  the  CP  server  or 
manually  on  other  Parallels  Fl-Sphere  servers. 


Item 

Comment 

Control  Panel  Server 

/hsphere /local /home/ cpanel/ hsphere /WEB- 
INF/classes/psof t config/ 

Parallels  H-Sphere  configuration  and  properties  files 

/hsphere/ shared/ SiteStudio/ studio/WEB- 
INF/classes/psof t config/ 

Parallels  SiteStudio  configuration  and  properties  files 

/hsphere /local /home / cpane 1/ apache /etc/ 

Apache  configuration  and  properties  files 

/hsphere /local /home/ cpane 1/ hsphere /WEB- 
INF/  classes/ shiva -templates/ IMAGES/ 

Control  Panel  icons  and  images 

/hsphere /local /home/ cpane 1/ hsphere /WEB- 
INF/  classes  /custom/ 

Custom  Control  Panel  templates,  etc. 

/ hsphere / shared/ SiteStudio/var/ websites 
/ 

Parallels  SiteStudio  user  data 

/var/ lib /pgsqi/ 

Parallels  H-Sphere  and  Parallels  SiteStudio  system 
databases  and  database  settings 

/hsphere/local/home/ cpanel/ . kb/ 
/hsphere/local/home/ cpanel/ . attachments 
/ 

Parallels  H-Sphere  knowledge  bases 

/hsphere /local /home /cpanel/ shiva /packag 
es 

Parallels  H-Sphere  packages 
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Web  Server 

/hsphere/ local /home/ 

User  Home  Directories 

/usr/ local /frontpage/ 

FrontPage  Extensions  settings 

/ hsphere /local/con fig/ 

httpd  and  ftp  configs 

/var/spool/cron/  (Linux) 

/var/cron/tabs/  (FreeBSD) 

Customer  Crontabs 

/hsphere/ shared/ apache/htdocs/phpMyAdmi 
n/config.inc. php 

phpMyAdmin  configuration  file 

/hsphere/ shared/ apache/htdocs/phpPgAdmi 
n/conf/config.inc. php 

phpPgAdmin  configuration  file 

/hsphere /local/ network/ 

ips  file,  etc. 

/hsphere/ shared/ awstats/wwwroot/ cgi- 
bin/ 

AWS  configs  et  al. 

Mail  Server 

/hsphere/ local /var/vpopmail /etc/ 

vpopmail  settings 

/ hsphere /local/var/vpopmail/ domains/ 

Mail  domains 

/ var/ qmail/ control/ 

Settings  for  qmail  addons 

/var/qmail /users/ 

qmail  users 

/ hsphere /local/con fig/ 

httpd  and  ftp  configs 

/var/lib/mysql/  (Linux) 

/var/db/mysql/  (FreeBSD) 

MySQL  databases  (used  to  store  user  settings 
for  integrated  antispam  and  antivirus  software) 

/ hsphere / shared/ apache /htdocs/ horde /con 
fig/ conf . php 

Horde  settings 

DNS  Server 

/etc /named .conf 
/etc/rndc . conf 

Main  DNS  config  files 

/hsphere /local /var/ named/ 

DNS  zone  files 

MySQL  Server 

/var/lib/mysql/  (Linux) 

/var/db/mysql/  (FreeBSD) 

MySQL  settings  and  databases 

User  PostgreSQL  Server 

/var/lib/pgsql/  (Linux) 

/usr/local/pgsql/  (FreeBSD) 

User  postgres  settings  and  databases 
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Recovering  Parallels  H-Sphere  Control 
Panel 


This  document  provides  a general  outline  on  how  to  recover  Parallels  H-Sphere 
Control  Panel  to  a new  server  if  the  old  one  has  crashed  due  to  hardware  or  other 
problems.  We  will  be  looking  into  two  situations: 

■ You  have  been  having  hardware  problems  that  didn’t  affect  the  HDD,  and  you  can 
access  the  HDD.  This  also  applies  to  hacked  servers.  In  this  case,  you’ll  have  to 
mount  the  HDD  of  the  crashed  server  to  the  new  server  to  copy  below  system  data 
from  it. 

■ You’ve  had  a HDD  failure  and/or  the  HDD  is  inaccessible.  In  this  case,  you’ll  have 
to  restore  below  system  data  from  a backup  (on  page  325). 

In  either  case  it  is  presumed  that  your  old  server  is  down  and  no  Parallels  H-Sphere 
servers  are  running. 

This  instruction  doesn’t  give  file/directory  locations  for  FreeBSD,  because  Linux  is  the 
recommended  operating  system  for  the  CP  server. 

Step  1 . Prepare  for  the  Recovery 

1.  On  the  target  server,  install  exactly  the  same  version  of  Parallels  H- 
Sphere  Control  Panel  as  on  the  source  server. 

2.  Make  sure  the  source  and  target  servers  have  the  same  versions  of  all 
software  packages.  For  example,  make  sure  that  the  target  server  has 
the  same  version  of  PostgreSQL  as  the  source  server. 

3.  Stop  Parallels  H-Sphere  CP  (on  page  41)  and  stop  PostgreSQL  service 
(on  page  42)  on  the  target  server. 

Step  2.  Recover  System  Data 

1.  Log  into  the  target  server  as  root. 

2.  Copy  files  and  directories  in  the  table  below  from  the  source  server  or 
backup  to  the  target  server. 

■ If  you  are  recovering  from  a backup  made  by  the  backup  script  (on  page  325), 
untar  the  backup  archive  copy  the  below  directories. 

■ If  you  are  recovering  data  from  the  HDD  of  the  crashed  server,  just  copy  the 
below  directories: 

rsync  -arlpogvzt  -e  ssh  SOURCE_SERVER_IP : DIRECTORY _PATH 
TARGET  DIRECTORY  PATH 
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3.  Restore  the  backed  up  SSH  keys  from  the 

~cpanel /. ssh/ identity . pub  and  ~cpanel / . ssh/ id_dsa . pub 
into  the  /root/.ssh/ authori zed_keys  and 

/ root/  . ssh/ authori zed_keys2,  respectively,  instead  of  the  new 
keys  generated  on  the  target  server  after  Step  1 . Please  refer  the 
Generating  SSH  Keys  for  Parallels  H-Sphere  Servers  (on  page  94) 
document  for  details. 

4.  On  multiserver  Parallels  H-Sphere  cluster,  test  inter-server 
communication  via  SSH  without  login.  For  example: 

su  -1  cpanel 
ssh  root $cp_server_ip 

exit 

ssh  roots second  server  ip 

exit 

and  so  on. 

5.  Sometimes,  in  order  to  restore  some  core  templates  and  images,  you 
may  need  to  run  the  Parallels  H-Sphere  update  script  for  this  version 
with  the  hsonlycpupdate  option. 

6.  Start  Parallels  H-Sphere  CP  (on  page  41)  and  PostgreSQL  (on  page 
42)  on  the  target  server. 

Note:  If  PostgreSQL  does  not  run  smoothly  after  its  start,  remove  the  the 

postmaster . pid  file  in  /var/lib/pgsql 

7.  You  may  test  the  Parallels  H-Sphere  database  by  running: 

su  -1  cpanel  -c  'psql  hsphere' 

This  should  result  in  a successful  log  into  the  database  from  the  command  line. 


Files  and  Directories  To  Be  Recovered 


Item 

Comment 

-cpanel/shiva/psoft  config/ 

Parallels  H-Sphere  configuration  and 
properties  files 

/hsphere / shared/ SiteStudio/psoft  c 
onf ig/ 

Parallels  SiteStudio  configuration  and 
properties  files 

-cpanel /apache /etc/ 

Apache  configuration  and  properties  files 

-cpanel/ shiva/ shiva- 
templates/ IMAGES 

Control  Panel  icons  and  images 

-cpanel/ shiva/ custom 

Custom  Control  Panel  templates,  etc. 

/ hsphere / shared/ SiteStudio/var/ web 
sites 

Parallels  SiteStudio  user  data 

/var/lib/pgsql  (on  Linux) 
/usr/local/pgsql  (on  FreeBSD) 

Parallels  H-Sphere  and  Parallels  SiteStudio 
system  databases  and  database  settings 

-cpanel/ . kb/ 

-cpanel/ . attachments/ 

Parallels  H-Sphere  knowledge  bases 
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-cpanel/ . ssh/identity .pub 
-cpanel/ . ssh/id_dsa.pub 


SSH  keys  to  be  restored  into  the 

/root/ . ssh/authorized_keys  and 
/root/ . ssh/authorized_keys2, 

respectively,  instead  of  the  new  keys 
generated  on  the  target  server  after  Step  1 
(fresh  Parallels  H-Sphere  installation). 


Recovering  Unix  Hosted  Parallels  H- 
Sphere  Servers 

This  document  explains  how  to  recover  non-CP  Linux/FreeBSD  boxes.  If  you  are 
restoring  CP,  see  Recovering  Control  Panel  (on  page  328). 

Important:  To  successfully  recover  a crashed  server,  you  must  meet  the  following 
requirements: 

1 . You  must  have  all  user  content  and  configuration  files  previously  backed  up  (on 
page  325). 

2.  You  must  have  the  physical  and  logical  server  structure  of  the  crashed  server 
preserved  in  the  administrator  CP  in  the  E. Manager  menu. 

We  suggest  the  procedure  below. 


In  this  section: 


Step  1 . Prepare  Crashed  Server  for  Recovery 330 

Step  2.  Run  Parallels  H-Sphere  Updater 331 

Step  3.  Run  the  Recovery  Tool 331 

Step  4.  Restore  User  Content 331 


Step  1 . Prepare  Crashed  Server  for  Recovery 

1.  Prepare  the  server  where  the  crashed  box’s  services  and  content  are  to 
be  restored,  according  to  Parallels  H-Sphere  installation  requirements 
described  in  the  Installation  Guide. 

2.  Make  sure  this  “blank”  server  is  bound  to  the  same  IP  the  crashed 
server  had. 

3.  Place  the  cpanel  user’s  public  SSH  keys  (on  page  94)  from  the  CP 
server  to  the  server  to  be  recovered  so  that  you  can  connect  via  SSH 
from  CP  server’s  root  to  the  new  box  without  password. 
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Step  2.  Run  Parallels  H-Sphere  Updater 

1.  Log  into  the  CP  server  as  root: 

$ su  -l 

2.  Download  the  update  script  of  the  Parallels  H-Sphere  version  you  were 
running  on  the  crashed  server.  If  you  already  have  an  older  version  of 
the  updater  in  the  current  directory,  please  remove  or  rename  this  file 
before  the  download. 

3.  Run  the  updater  on  the  directory  where  you  have  downloaded  it.  See 
the  Update  Guide  for  details. 

4.  Restore  the  crashed  server  software  by  typing  in  the  following 
command  in  the  updater’s  command  line  prompt: 
hspackages  ips=<CRASHED_SERVER_IP> 


Step  3.  Run  the  Recovery  Tool 

Web,  Mail,  MySQL,  PgSQL  servers:  To  restore  your  Parallels  H-Sphere  physical 
resources  (Unix  users  and  configuration),  log  in  as  the  cpanel  user  (on  page  53)  and 
run  PhysicalCreator  (on  page  60). 

Note:  Do  not  confuse  the  account  ID  with  the  server  ID  you  used  when  generating 
configuration  files.  Account  IDs  could  be  found  in  the  accounts  table  of  the  Parallels  H- 
Sphere  system  database. 

DNS  server:  For  DNS  servers,  log  in  as  the  cpanel  user  (on  page  53)  and  run  DNS 
Creator  (on  page  194): 

java  psoft . hsphere . tools . DNSCreator  -m  db 


Step  4.  Restore  User  Content 

To  restore  data  from  the  backup,  check  with  the  backup  and  recovery  list  (on  page 
326)  for  for  this  server.  Restore  listed  directories  from  /var/backup / <ARCHIVE> . tgz 
or  custom  backup  directory  into  the  appropriate  locations. 

More  on  backup  recovery  (on  page  332). 
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Restoring  Files  and  Directories  from 
Backup 

This  document  explains  how  to  recover  Parallels  H-Sphere  user  and  system  data  you 
have  backed  up  according  to  the  manual  on  backing  up  Parallels  H-Sphere  (on  page 

325) . 

Parallels  H-Sphere  backup  location  is  set  in  the 

/hsphere/ shared/backup/hs_bck . cf g config  file.  The  default  location  is 

/ var/backup. 

hs_bck  stores  the  system  data  backup  (with  user  content  if  configured  in 
hs_bck.  cfg)  in  the  following  files  in  the  bck_dir  directory: 

■ <ARCHIVE> . tgz  - the  latest  backup;  <ARCHIVE>  is  the  name  of  the  backup  file  set  in 
hs_bck.  cfg.  This  is  the  default  name: 

BACKUP  hs_bck 

Older  backup  files  are  named  <ARCHIVE> . l . tgz,  <ARCHIVE> . 2 . tgz,  ... 

■ hsphere . sqi  - the  Parallels  H-Sphere  system  database  backup 

■ counter . sqi,  poll . sqi,  guestbook . sqi  - Parallels  SiteStudio  system 
databases  are  also  backed  up  if  Parallels  SiteStudio  is  set  up  with  Parallels  H- 
Sphere. 

To  restore  data  from  the  backup,  check  with  the  backup  and  recovery  list  (on  page 

326)  for  the  directories  that  need  to  be  recovered  for  this  server.  Restore  these 
directories  from  <ARCHIVE> . tgz  into  the  appropriate  locations  on  the  server. 


Restoring  the  Parallels  H-Sphere  System 
Database  From  Backup 

This  documentation  explains  how  to  restore  the  Parallels  H-Sphere  system  database 
from  a backup  made  by  the  Parallels  H-Sphere  hs_bck  (on  page  325)  script.  If  you 
back  up  your  system  PostgreSQL  database  manually  using  pg_dump,  the  procedure 
would  be  basically  the  same,  except  for  the  backup  names  and  locations. 

The  backup  destination  directory  for  the  /hsphere/shared/backup/hs_bck  script 
is  set  in  the  /hsphere/ shared/backup/hs_bck . cfg  config  file.  The  default 
location  is: 

BCK_DIR  /var/backup 

hs_bck  stores  the  system  data  backup  in  the  following  files  in  the  bck_dir  directory: 

■ <ARCHIVE>Agz  - the  system  data  content;  <ARCHIVE>  is  the  name  of  the  backup  file 

set  in  hs  bck . cfg: 

BACKUP  hs_bck 

Older  backup  files  are  named  <ARCHIVE> . l . tgz , <ARCHIVE> . 2 . tgz , ... 

■ hsphere . sqi  - backup  of  the  Parallels  H-Sphere  system  database 
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■ counter . sqi,  poll . sqi,  guestbook . sqi  - Parallels  SiteStudio  system 
databases  are  also  backed  up  if  Parallels  SiteStudio  is  integrated  with  Parallels  H- 
Sphere. 

Below  are  two  cases  restoring  the  database  depending  on  PostgreSQL  installed  or  not 
on  the  server. 


In  this  section: 

Restoring  the  Parallels  H-Sphere  Database  on  a Server  with  PostgreSQL  Not  Installed  334 
Restoring  the  Parallels  H-Sphere  Database  Content  if  PostgreSQL  Is  Installed :335 
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Restoring  the  Parallels  H-Sphere  Database  on  a Server 
with  PostgreSQL  Not  Installed 

1.  Log  into  the  erver  as  root: 

su  - 

2.  Install  PostgreSQL  to  the  server. 

3.  Start  PostgreSQL  for  the  first  time: 

On  RedHat  servers: 

/ etc/ rc . d/ ini t . d/postgresql  start 

On  FreeBSD  servers , you  need  to  initiate  the  PostgreSQL  service  database 
manually  before  you  start  Postgres: 
su  - pgsql  -c  initdb 

/usr/local/etc/ rc . d/010 .pgsql . sh  start 

4.  Log  in  as  PosgreSQL  user: 

On  RedHat  servers  (the  PostgreSQL  service  database  is  initiated  automatically  on 
login): 

su  - postgres 
On  FreeBSD  servers : 
su  - pgsql 

5.  Create  the  user  wwwuser: 
createuser  wwwuser 
Answer  yes  to  all  prompts. 

6.  Enter  the  PostgreSQL  service  database: 

psql  templatel 

7.  Restore  the  wwwuser  password: 

alter  user  wwwuser  with  password  'old_pas sword' ; 
alter  user  pgsql  with  password  'old_j?as sword'  ; 

Here,  old_password  is  the  wwwuser  password  to  be  restored. 

8.  Quit  from  PostgreSQL: 

\q 

9.  Configure  PostgreSQL  passwords  in  the 
~pgsql/data/pg_hba  . conf  file,  according  to  instructions  provided  in 
this  file. 

10. Optimize  Postgres  (on  page  87)  for  better  PostgreSQL  performance  on 
powerful  servers,  esp.  when  the  database  is  large  (more  than  1GB). 

Note:  It  is  helpful  to  set  f sync=false  in  postgresql . conf  for  the  time  of 
recovery.  This  allows  to  speed  up  the  process.  However,  please  beware  that  this 
may  damage  the  database  integrity,  and  we  recommend  using  this  option  only  on 
reliable  hardware!  Don’t  forget  to  return  to  fsync=true  after  the  recovery  is 
complete! 


11. Restart  PostgreSQL  (on  page  42). 
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12. Create  Parallels  H-Sphere  database  by  running: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 
Parallels  SiteStudio  databases  are  created  in  the  similar  way. 

13. Import  the  database  content  from  the  backup: 

psql  -U  wwwuser  -f  </-/S_BCK>/hsphere . sql  hsphere 

where  <HS_BCK>  is  the  backup  directory.  Parallels  SiteStudio  databases  are 
imported  in  the  similar  way. 

Restoring  the  Parallels  H-Sphere  Database  Content  if 
PostgreSQL  Is  Installed: 

1.  Log  in  to  the  CP  server  as  root: 

su  - 

2.  Drop  the  Parallels  H-Sphere  database: 

dropdb  -U  wwwuser  hsphere 

3.  Create  the  Parallels  H-Sphere  database: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 

4.  Optimize  Postgres  (on  page  87)  for  better  PostgreSQL  performance  on 
powerful  servers,  esp.  when  the  database  is  large  (more  than  1GB). 

Note:  It  is  helpful  setting  f sync=faise  in  postgresqi . conf  for  the  time  of 
recovery.  This  allows  to  speed  up  the  process.  However,  please  beware  that  this 
may  damage  the  database  integrity,  and  we  recommend  using  this  option  only  on 
reliable  hardware!  Don’t  forget  to  return  to  fsync=true  after  the  recovery  is 
complete! 

5.  Import  the  database  content  from  the  backup: 

psql  -U  wwwuser  -f  <HS_BCK>/ hsphere.  sql  hsphere 
where  <HS_BCK>  is  the  backup  directory. 

Parallels  SiteStudio  databases  are  restored  in  the  same  way. 
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Fixing  Crashed  Parallels  H-Sphere 
Database 


Sometimes  PostgreSQL  database  can  get  corrupted  to  the  point  of  no  return.  That 
might  manifest  itself  in  things  like: 

hsphere=#  VACUUM  ; 

ERROR:  Relation  71343  does  not  exist 

This  usually  means  that  index  is  corrupted. 

> To  recover  from  the  problem: 

1.  Login  as  root: 

su  - 

2.  Stop  Postgres  (on  page  41)  if  it  is  running. 

3.  Make  sure  that  no  Postgres  processes  are  running  using  the  command: 

ps  auxw  | grep  post 

If  any  of  them  are  running,  kill  them. 

4.  Remove  Postgres’  pid  file: 

rm  -f  PGSQL_HOME/data/postmaster . pid 

From  now  on,  we  note  PGSQL_HOME  as  the  Postgres  home  directory  which  is 

/var/lib/pgsqi  on  RedHat  servers,  and  /usr/iocai/pgsqi  on  FreeBSD. 

5.  Switch  to  Postgres  user: 

# su  - postgres  (on  RedFlat) 

# su  - pgsql  (on  FreeBSD) 

6.  Backup  PostgreSQL  database  stored  in  the  pgsql_home/ data 
directory: 

cp  -r  PGSQL_HOME/data  pgdata . backup 

7.  Try  to  connect  to  the  Parallels  H-Sphere  database  in  single  mode: 

postgres  -D  PGSQL_HOME/data  -O  -P  hsphere 
There  can  be  errors  like: 

FindExec:  found  “/usr/bin/postmaster”  using  argv[0] 

2002-03-22  13:42:46  [6002]  DEBUG:  database  system  was  shut  down  at  2002-03-22 
11:46:11  CET 

2002-03-22  13:42:46  [6002]  DEBUG:  ReadRecord:  invalid  resource  manager  id  157  at 
(0,  561372168) 

2002-03-22  13:42:46  [6002]  DEBUG:  Invalid  primary  checkpoint 
record 

2002-03-22  13:42:46  [6002]  DEBUG:  Invalid  RMID  in  secondary  checkpoint  record 
2002-03-22  13:42:46  [6002]  FATAL  2:  Unable  to  locate  a valid  Checkpoint  record 
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2002-03-22  13:42:46  [6002]  DEBUG:  proc_exit(2) 

2002-03-22  13:42:46  [6002]  DEBUG:  shmem_exit(2) 

2002-03-22  13:42:46  [6002]  DEBUG:  exit(2) 

/usr/bin/postmaster:  reaping  dead  processes... 

/usr/bin/postmaster:  Startup  proc  6002  exited  with  ... 

The  messages  like: 

ReadRecord:  invalid  resource  manager 

and  other  are  culprit  of  the  error. 

In  case  of  the  above  errors,  do  the  following: 

1.  Execute: 

pg_resetxlog  PGSQL_HOME/data 

(this  will  reset  the  write-ahead  log  and  other  control  information  of  a PostgreSQL 
database  cluster;  they  are  important  but  this  is  the  only  way  to  recover). 

2.  Try  to  log  into  Postgres  again  in  single  mode: 

postgres  -D  PGSQL_HOME/data  -O  -P  hsphere 

3.  Once  you  are  in,  type: 

reindex  database  hsphere; 

4.  Exit  the  database: 

\q 

5.  Finally,  start  Postgres  (on  page  41)  and  see  if  everything  is  working. 
Here,  two  Postgres  tools  are  used: 

■ reindex  database  to  recover  corrupted  indexes 

■ pg_resetxiogs  to  reset  write-ahead  log  files  and  the  state  of  Postgres. 


Backing  Up  Winbox 

This  document  explains  how  to  back  up  your 

■ Windows  server  settings  stored  in  the  MetaBase, 

■ MS  SQL  database 

■ user  content 

In  this  section: 


Backing  Up  the  Metabase 338 

Backing  Up  MS  SQL  Databases 338 

Backing  Up  User  Content 338 
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Backing  Up  the  Metabase 

1.  Go  to  Start  ->  Programs  ->  Administrative  Tools  ->  Computer 
Management. 

2.  In  the  left  tree,  unfold  Services  and  Applications. 

3.  Right-click  Internet  Information  Services  and  select  Backup/Restore 
Configuration. 

4.  In  the  window  that  appears,  click  Create  Backup. 

Usually,  IIS  metabase  backup  files  are  located  in  the  following  directory: 

C : \WINNT\system32\inetsrv\MetaBack\ 

Backing  Up  MS  SQL  Databases 

1.  Go  to  Start  ->  Programs  ->  Microsoft  SQL  Server  ->  Enterprise 
Manager. 

2.  Unfold  the  left  menu  tree  until  you  see  the  name  of  the  logical  server. 
Click  it. 

3.  Click  Tools  on  the  toolbar  and  select  Backup  Database. 


Backing  Up  User  Content 

1.  Go  to  Start ->  Programs  ->  Accessories  ->  System  Tools  ->  Backup. 

2.  Select  Backup  Wizard 

3.  On  the  first  step  of  the  wizard,  select  Back  up  selected  files,  drives,  or 
network  data. 
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Recovering  Winbox 

This  document  explains  how  to  restore  Parallels  H-Sphere  Winbox  configuration  using 
the  Physical  Creator  (on  page  60)  utility.  If  you  have  access  to  user  homes,  you  can 
recover  user  content  from  this  directory.  If  you  don’t,  you’ll  need  an  earlier  backup  (on 
page  337)  with  preserved  directory  structure  (on  page  220). 

We  suggest  the  recovery  procedure  below. 

In  this  section: 

Step  1 . Back  Up  User  Content 339 

Step  2.  Install  Parallels  H-Sphere 340 

Step  3.  Set  Up  Dedicated  IPs 340 

Step  4.  Prepare  Target  Winbox  for  Physical  Creator 340 

Step  5.  Run  PhysicalCreator  on  the  CP  Box 341 

Step  6.  Restore  Content  from  Backup 342 

Step  7.  Install  Shared  SSL 343 

Step  8.  Set  Correct  NTFS  Permissions  and  Owner  for  the  Home  Directory 344 

Step  1 . Back  Up  User  Content 

1.  Stop  IIS  by  running  the  following  commands  from  the  command  prompt: 

iisreset  /stop 
net  stop  w3svc 
net  stop  ftp 

2.  Rename  the  directory  containing  Parallels  H-Sphere  user  homes.  It  will 
be  used  later  to  recover  user  content.  If  you  don’t  have  access  to  user 
homes,  you’ll  have  to  recover  user  content  from  a backup. 

3.  Start  IIS: 

iisreset  /start 

4.  Create  an  empty  HSHOME  directory 
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Step  2.  Install  Parallels  H-Sphere 

1.  Make  sure  to  have  IIS  (WebService)  and  FTP  (IIS  or  Serv-U)  installed. 
For  information  on  IIS,  run  from  the  command  prompt: 
%SystemRoot%\System32\Inetsrv\iis .msc 

For  information  on  Serv-U  FTP,  check  the  task  manager  or  Service  Managere  (full 
name  : Serv-U  FTP  Server,  short  name:  servu) 

FTP  can  be  missing  if  the  server  is  running  only  MS  SQL. 

2.  Follow  Winbox  preinstallation  procedure  as  suggested  in  the  Winbox 
Installation  Guide. 

3.  Follow  Winbox  installation  procedure. 

4.  After  the  installation,  set  up  WebShell4. 


Step  3.  Set  Up  Dedicated  IPs 

1.  Go  to  the  Parallels  H-Sphere  admin  control  panel  and  select  the 
Winbox  in  L. Servers  of  the  E. Manager  ->  Servers  menu. 

2.  Copy  all  Busy  Dedicated  IPs  and  their  netmasks  from  the  list  of  IPs  into 
a text  file  the  IPs  to  create  a file  with  the  following  format: 

192.0.34.166  255.255.255.0 
160.79.224.130  255.255.255.0 
81.3.94.100  255.255.255.0 

3.  Download  IpCreator: 

http://download.hsphere.parallels.com/shiv/WinBox/ipcreator.exe. 

4.  Bind  IPs  using  the  IpCreator  utility,  passing  the  file  with  IPs  as  a 
parameter: 

IpCreator . exe  FILE_WITH_IPS  > log.txt 

Step  4.  Prepare  Target  Winbox  for  Physical  Creator 

In  the  command  prompt  of  the  Winbox  server,  run: 
net  stop  HsQuotas 


Backup  and  Recovery  341 


Step  5.  Run  PhysicalCreator  on  the  CP  Box 

1.  Go  to  the  Parallels  H-Sphere  admin  control  panel,  select  P.Servers  of  the 
E. Manager  ->  Servers  menu,  and  click  server  info  for  the  Winbox  in 
question. 

2.  Check  if  server  info  shows  on  the  page  that  appears.  If  not,  the  CP 
server  can’t  communicate  with  the  Winbox;  make  sure  to  fix  this  issue 
before  proceeding. 

3.  Downolad  tail  utility  for  Windows 
(http://download.hsphere.parallels.com/shiv/WinBox/tail.exe)  and  put  it 
into  the  windows  (win2003)  or  winnt  (win2000)  directory. 

4.  Log  into  the  system  database  (on  page  53)  and  run  the  following  DB 
query  to  find  out  the  number  of  domains  to  create: 

select  count (*)  from  iis  vhost  i, parent  child  p, accounts 
a, user  account  ua  where  i.id=p. child  id  and  p. account  id  = 
a. id  and  a. deleted  is  null  and  ua. account  id  = a. id  and 
(a. demo  <>  1 OR  demo  IS  NULL)  and  host  id  = ???; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

5.  Run  PhysicalCreator  as  the  cpanel  user  (on  page  53): 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  LOGICAL_SERVER_ID  > creator.log  2>&1  & 

6.  In  the  command  line  on  the  Winbox,  run  tail  -f  action,  log  to 
monitor  the  creation  of  Winbox  resources. 

7.  In  another  command  line  window,  periodically  check  the  number  of 
created  domains  by  running: 

find  "CreateWebHost ("  CHS  DIRECTORY>\logs\action . log  /c 

for  example: 

find  "CreateWebHost ("  d:\hsphere\logs\action.log  /c 
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Step  6.  Restore  Content  from  Backup 

1.  Update  Parallels  H-Sphere  to  restore  original  skeleton  and  renamed 
scripts. 

2.  Back  up  IIS  metabase  using  built-in  IIS  backup  tools. 

3.  Stop  IIS: 

iisreset  /stop 
net  stop  w3svc 
net  stop  ftp 

4.  Copy  user  content  to  the  directory  for  user  homes. 

5.  Start  IIS: 

iisreset  /start 

6.  In  the  command  prompt  of  the  Winbox  server,  run: 
net  start  HsQuotas 
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Step  7.  Install  Shared  SSL 

1.  In  the  admin  control  panel,  install  completely  new  Certificate  key  and 
file  pair  as  described  in  Parallels  H-Sphere  Service  Administrator 
Guide.  You  can  get  them  in 

/hsphere/ shared/ apache/ conf  / ssl . shared/ <domain.name> / on 

any  Unix/Linux  web  server.  This  will  repost  the  wildcard  certificate  on  all 
servers,  including  the  Winbox  you  are  recovering. 

2.  Download  Recreation  scripts 

(http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScript 

s.zip)  in  a zip  archive  and  unpack  them  to  a separate  directory  on  the 
Winbox,  for  example  recreation_scripts. 

3.  Log  into  the  system  database  (on  page  53)  and  run  the  following  DB 
query  to  select  the  domain  names  with  shared  SSL  enabled: 

select  s . name , hostnum, d . name  from  shared  ssl  s,  parent  child 
pi,  parent  child  p2 , domains  d,  iis  vhost  h where  s.id  = 
pi . child  id  and  pi. parent  id  = p2. child  id  and  p2. parent  id  = 
d.id  and  p2. child  id  = h.id  and  h.host  id=  ???; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

4.  Copy  results  of  the  query  into  a text  file  in  the  recreation_scripts 
directory  and  name  it,  for  instance,  S_SSL.txt.  It  will  have  the  following 
format: 

snamel  | hostnuml  | domain  namel 

sname2  | hostnum2  | domain  name2 

snameN  | hostnumN  | domain  nameN 

where: 

snamex  is  the  third  level  domain  secured  with  the  wildcard  certificate,  e.g. 

user22 . yourdomain . com 

hostnumx  is  the  domain  ID  in  IIS 

domain_namex  is  the  corresponding  second  level  domain,  e.g.  user22.com. 

5.  Enter  the  recreation_scripts  directory  and  run  the  following 
command: 

sslprepare.bat  %1  %2  %3  %4  %5  > SetSSL.txt 
where: 

rem  %i  is  the  file  name  you  have  created  (e.g.  s_ssl  . txt) 
rem  %2  - Winbox  IP 

rem  %3  - Service  domain  used  for  shared  SSL 

rem  %4  - Parallels  H-Sphere  login  used  at  Winbox  installation 

rem  %5  - Parallels  H-Sphere  password  used  at  Winbox  installation. 

6.  Open  SetssL . txt  and  remove  the  first  part  leaving  only  the  list  of 
links. 

7.  Run  the  following  command: 

WGET.EXE  -i  SetSSL.txt 

This  will  recreate  all  Shared  SSL  resources  on  the  Winbox. 
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Step  8.  Set  Correct  NTFS  Permissions  and  Owner  for 
the  Home  Directory 

1.  Download  SetScrt  Tool: 

http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 

2.  Run  it  to  set  correct  owner  and  NTFS  permissions  on  user  home 
directories: 

SetScrtNs20  /f tp : <number>  /users :<file> 
where: 

ftp  - default  Parallels  H-Sphere  ftp  host  number 
users  - user  list  file 

3.  Check  the  log  files  for  report. 

Note:  Read  on  NTFS  Permissions  (on  page  244) 
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Recovering  Winbox  Quota 

> To  recover  Winbox  quota: 

1.  Download  Recreation  scripts 

(http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScript 

s.zip)  in  a zip  archive  and  unpack  them  to  a separate  directory  on  the 
Winbox,  for  example  recreation_scripts. 

2.  Log  into  the  system  database  (on  page  53)  and  run  the  following  DB 
query  to  select  the  users  and  their  space  limit: 

select  unix  user. login,  quotas. size  mb  from  unix  user, 
parent  child,  quotas  where  hostid=???  and 
parent  child. parent  id=unix  user. id  and 
parent  child. child  id=quotas.id  and 
parent  child. child  type=4001; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

3.  Copy  results  of  the  query  into  a text  file  in  the  recreation_scripts 
directory  and  name  it,  for  instance,  quotat.txt. 

4.  Enter  the  recreation_scripts  directory  and  run  the  following  command: 
Rquota.bat  %1  %2  %3  %4  > quota.txt 

where: 

rem  %l  - file  name,  e.g.  quota.txt 
rem  %2  - Winbox  IP 

rem  %3  - Parallels  H-Sphere  login  used  at  Winbox  installation 
rem  %4  - Parallels  H-Sphere  password  used  at  Winbox  installation 

5.  Open  quota . txt  and  remove  the  first  part  leaving  only  the  list  of  links. 

6.  Run  the  following  command: 

WGET.EXE  -i  quota.txt 

This  will  recreate  quota  resource  on  the  Winbox. 
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Like  all  third  party  commercial  products,  Miva  Empresa  and  Miva  Merchant  are 
purchased  and  installed  separately  from  Parallels  H-Sphere.  Miva  Merchant 
(http://www.miva.com/products/merchant)  requires  Miva  Empresa 
(http://www.miva.com/products/empresa)  also  known  as  Miva  Virtual  Machine  or 
‘mivavm’  for  web  server  XML  scripting,  e-commerce  and  database  capabilities. 

■ Miva  Merchant  5.x  is  supported  starting  with  Parallels  H-Sphere  2.4.3  Patch  1 
inclusive.  It  requires  Miva  Empresa  5.02  and  higher. 

■ Miva  Merchant  4.14  and  later  is  supported  from  Parallels  H-Sphere  2.3  RC  4 
inclusive.  It  requires  Miva  Empresa  4.02  and  higher. 

For  extensive  coverage  of  Miva  products,  please  visit  http://www.miva.com/products. 

In  this  chapter: 
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Miva  Installation  for  Windows 351 

Updating  Miva  4 to  Miva  5 352 


Miva  Installation  for  *nix 
Requirements 

■ Installed  and  properly  configured  Parallels  H-Sphere  system. 

■ One  valid  Miva  Empresa  license. 

■ At  least  one  valid  Miva  Merchant  license. 

In  this  section: 
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Miva  Merchant  Installation 349 
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Miva  Empresa  Installation 

> To  install  Miva  Empresa: 

1.  Log  into  the  web  server  as  root. 

2.  Change  directory  to  /hsphere/shared/miva.  If  you  don’t  have  this 
directory,  create  it  first  and  set  ownership  to  root : root  and 
permissions  to  755: 

mkdir  /hsphere/shared/miva 

chown  root: root  /hsphere/shared/miva 

chmod  755  /hsphere/shared/miva 

3.  Download  Miva  virtual  machine  distribution  file  from 
http://www.miva.com/products/empresa/download/  to 

/hsphere/shared/miva. 

Linux:  mivavm-vX.  XX-linux  glibc2  . tar  . gz 
FreeBSD:  mivavm-vX . XX-freebsd  45.tar.gz 

Here,  mivavm  is  the  product  name,  vx.xx  its  version  name,  iinux_giibc2  is 
Linux  glibc2  package,  freebsd_45  is  FreeBSD  4.5  operation  system. 

4.  Untar  the  unloaded  file: 
tar  xfz  <DistributionFileName> 

5.  Move  the  content  of  the  directory  mivavm-vX . xx  to 
/hsphere/ shared/mi va: 

mv  mivavm-vX . XX/*  . 
rm  -rf  mivavm-vX. XX 

6.  Set  ownership  to  root:root  on  the  content  of  the  directory 
/hsphere/ shared/mi va: 

chown  -R  root: root  /hsphere/shared/miva 

7.  Move  file  cgi-bin/mivavm-vx . xx  to  directory 
/hsphere/shared/miva: 

mv  cgi-bin/mivavm-vX . XX  mivavm 

8.  If  you  need  to  use  commerce  libraries  you  got  from  Miva,  copy  them  to 
directory  lib/commerce,  then  create  links  to  them  as  follows: 

In  -s  /hsphere/ shared/mi va/lib/commerce/uupsrss-vX . XX-linux- 
glibc2 . so 

/hsphere/ shared/miva/lib/ commerce/uupsrss . so 

In  -s  /hsphere/ shared/mi va/lib/commerce/cybercash-vX . XX- 

linux-glibc2 . so 

/hsphere/ shared/mi va/ lib/ commerce/ cybercash . so 
In  -s  /hsphere/ shared/mi va/lib/commerce/ics2-vX . XX-linux- 
glibc2 . so  /hsphere/ shared/mi va/ lib/ commerce/ ics2 . so 
In  -s  /hsphere/ shared/mi va/lib/commerce/linkpoint-vX . XX- 
linux-glibc2 . so 

/hsphere/ shared/miva/lib/ commerce/linkpoint . so 

In  -s  /hsphere/ shared/mi va/lib/commerce/authnet-vX . XX-linux - 

glibc2 . so 

/hsphere/ shared/mi va/ lib/ commerce/authnet . so 
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9.  If  you  have  more  than  one  web  server,  repeat  the  above  steps  for  all 
web  servers  where  you  want  to  have  Miva  installed. 

When  the  Miva  Empresa  resource  is  turned  on: 

■ In  the  domain  home  directory 

(/hsphere/ local /home /<user_name>/<domain_name>/),  the  cgi-bin  is 

createdthe  mivavm  and  mivavm.  conf  files  are  copied  to  this  cgi-bin  directory 

■ the  libmivaconf  ig . so  Symlink  to 

/hsphere/ shared/miva/lib/ conf  ig/ 3x . so  is  Created  there 

■ In  the  user  home  directory  (/hsphere/iocai/hom e/<user_name>/),  create  the 
mivadata  directory,  and  the  <domain_name>  subdirectory  there,  with  the  same 
name  as  the  domain  subdirectory  in  the  user  home  directory. 

■ In  the  Apache  configuration  file  for  this  domain,  the  Miva  compiled  script  MIME  type 
is  added: 

application/x-miva-compiled  .mvc 

Here, 

■ mivavm  is  a CGI  application  that  executes  complied  Miva  scripts; 

- mivavm.  conf  is  the  Miva  Empresa  configuration  file. 

The  mivavm.  conf  file  may  look  like  this: 

mivaroot=& [ document  root] 

stdmodedatadir=/hsphe re /local /home /miva /mi vadat a/mi va . com 

securityoptions=15 

< COMMERCE -LIB  METHOD=  "UPSCost" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ upsrss . so"> 

< COMMERCE -LIB  METHOD=  "CyberCash" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ cyber cash . so"> 

< COMMERCE -LIB  METHOD=  "ICS2" 

LIBRARY="/hsphere/ shared/miva/lib/ commerce/ ics2 . so"> 

< COMMERCE -LIB  METHOD=  "LinkPoint" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ linkpoint . so"> 

< COMMERCE -LIB  METHOD=  "AuthorizeNet" 

LIBRARY="/hsphere/ shared/miva/lib/ commerce/ authnet . so"> 
<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/mi va/lib/builtins/ crypto . so"> 

<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/mi va/lib/builtins/ system. so"> 

<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/mi va/lib/builtins/ file. so "> 

<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/ miva /lib /built ins /math . so"> 

<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/mi va/lib/builtins/ string. so "> 

<BUILTIN-LIB  LIBRARY  = 

"/hsphere/ shared/mi va/lib/builtins/ time . so"> 
cadir=/hsphere/ shared/miva/ certs 
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opens sl=/ us r/ lib/ libs si . so 

opens sl_crypto=/usr/lib/libcrypto . so 

where: 

■ mivaroot  is  the  Miva  Web  root  directory,  the  same  as  the  domain’s 
DocumentRoot  directory 

■ stdmodedatadir  is  a directory  where  Miva  Empresa  data  is  stored 

■ commerce-lib  method  is  a Payment  Instrument , a commercial  library  to  support 
automatic  payments  from  credit  cards  via  merchant  gateway 

■ builtin-lib  library  is  a standard  (built-in)  library  that  contains  basic  system 
functions 

■ cadir  is  a directory  with  SSL  certificates 

■ openssi  is  the  path  to  the  OpenSSL  library 

■ opens  sl_cryp to  is  the  path  to  encryption  libraries 


Miva  Merchant  Installation 

> To  install  Miva  Merchant: 

1.  Log  into  the  web  server  as  root. 

2.  Copy  file  Merchant-vY  . YY-bundle  . tar  . gz  to 
/hsphere/  shared /miva.  vY . YY  is  Miva  Merchant  version. 

3.  Create  a link  to  Merchant-vY  . YY-bundle  . tar  . gz: 

In  -s  /hsphere/ shared/mi va/Merchant-vY. YY-bundle . tar . gz 
Merchant-bundle 

4.  In  the  admin  control  panel,  select  Globals  in  the  Plans  menu  and  make 
sure  Miva  Empresa  Engine  and  MIVA  Resource  are  enabled. 

5.  Select  L.Servers  in  the  E. Manager  ->  Servers  menu,  then  click  the  web 
server,  and  at  the  bottom  of  the  page  that  appears  select  the  version  of 
Miva  Merchant: 
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6.  If  you  have  more  than  one  web  server,  repeat  the  above  steps  for  all 
web  servers  where  you  want  to  have  Miva  installed. 

7.  Log  into  your  admin  Control  Panel,  select  Miva  Merchant  Lie.  in  the  3rd  party 
Tools  menu  and  enter  your  Miva  Merchant  licenses  : 

Notes: 


■ Login  and  Password  for  Miva  admin  interface  are  the  same  as  for  FTP  unless  a 
user  has  activated  the  original  Miva  Merchant  setup. 

■ If  Miva  is  enabled,  the  user  can’t  remove  the  cgi-bin  directory  and  CGI  handler  with 
the  . cgi  extension  in  Parallels  H-Sphere. 

■ mivadata  and  all  its  content  is  not  removed  when  Miva  resource  is  removed. 

■ To  make  Miva  work  via  SSL  (htpps),  an  SSL  certificate  is  required.  If  a user  cannot 
connect  to  Miva  site  by  SSL  (https://),  log  into  your  Miva  Merchant  control  panel  via 
http,  go  to  the  Domain  Settings  page  ->  Site  configuration  tab  and  check  secure 
URLs. 

■ You  can  install  two  instances  of  Miva  on  one  logical  server,  one  version  4.12  and 
older,  the  other  4.14  or  later. 

■ To  enable  Miva  Merchant  Follow  Symlinks  in  mivaroot  and  stddatadir,  you 
need  to  add  the  following  line  into  the  miva.conf  file: 
securityoptions=15 
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Miva  Installation  for  Windows 


It  is  recommended  to  install  Miva  products  prior  to  Parallels  H-Sphere  Winbox 
software.  If  you  choose  to  do  so,  simply  install  Miva  Empresa  and  Miva  Merchant 
following  Miva  documentation.  Afterwards,  install  Parallels  H-  Sphere  winbox  software, 
and  the  installation  wizard  will  guide  you  through  the  Miva  configuration  procedure. 

> To  install  Miva  on  a running  Winbox: 

1.  Install  Miva  Empresa  VM  as  described  at 
http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/install  miva  empresa  vm  on  windows 

2000  server.htm. 

2.  Install  Miva  Merchant  as  described  in  Miva  documentation  at 
http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/web  host  resources.htm. 

Note:  Since  version  3.1,  Parallels  H-Sphere  supports  only  Miva  5 for  Windows 
platforms.  If  you  move  to  Miva  5 and  need  to  upgrade  Miva  Merchant  stores,  follow 
the  instructions  at  http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/upqrade  to  merchant  5 from  merchant  4.htm. 

3.  Go  to  your  admin  control  panel,  select  E. Manager  ->  L.Servers,  click  the 
Windows  server,  and  at  the  bottom  of  the  page  that  appears  specify  the 
version  of  Miva  Merchant.  Specify  also  its  location  on  your  box: 
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4.  Run  Parallels  H-Sphere  Update  Wizard  from  the  administrator  control 
panel. 

5.  Optionally,  install  miva  commerce  libraries. 

6.  Log  into  your  admin  Control  Panel,  select  Miva  Merchant  Lie.  in  the  3rd  party 
Tools  menu  and  enter  your  Miva  Merchant  licenses. 

7.  Enable  Miva  in  your  hosting  plans. 

Once  you  have  enabled  Miva,  users  can  turn  them  on  in  their  control  panels.  User’s 
miva  login  and  password  are  same  as  for  FTP. 


Updating  Miva  4 to  Miva  5 

We  do  not  support  Miva  4 and  Miva  5 running  on  the  same  web  server.  To  upgrade 
Miva  Merchant  and  Miva  Empresa,  you  need  to  uninstall  version  4 and  then  set  up 
version  5.0. 

Since  these  two  versions  use  different  system  libraries,  customer  stores  also  need  to 
be  updated  to  Miva  5. 

To  update  the  stores,  please  use  Miva  tools,  as  we  do  not  provide  any  update  utilities. 
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Urchin 


This  chapter  describes  how  to  install  Urchin  4 and  Urchin  5 on  your  Parallels  H-Sphere 
servers. 

Urchin  4 and  5 can  be  installed  on  any  Parallels  H-Sphere  *nix  server.  It  does  not 
require  any  special  configuration  and  once  installed,  can  poll  statistics  from  all  web 
servers  and  winboxes. 

In  this  chapter: 


Urchin  4 and  5 Installation  on  Unix 354 

Urchin  4 and  5 Installation  on  Windows 355 

Urchin  4 And  Urchin  5 Database  Utilities 356 
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Urchin  4 and  5 Installation  on  Unix 

> To  install  Urchin: 

1.  Go  to  the  Urchin  home  page  (http://www.google.com/urchin/index.html) 
and  click  the  Download  link. 

2.  Select  the  installer  that  most  closely  matches  your  platform.  The  name 
of  the  installer  includes  the  Urchin  version  and  the  operating  system 
type  (e.g.,  urchin41 00_redhat6x.sh). 

Note:  Currently,  only  versions  5.7.03  and  below  are  supported. 

If  necessary,  upload  the  installer  to  a temporary  location  on  the  system  where  you 
are  installing  Urchin.  If  you  are  not  on  the  console,  telnet  (or  use  ssh  if  available)  to 
the  system  and  cd  to  the  directory  where  the  installer  is  located. 

3.  From  the  command  line,  type  the  name  of  the  installer.  For  example: 

. /urchin4100_redhat7x . sh 

This  unpacks  the  files  that  comprise  the  installation  kit. 

4.  From  the  command  line,  execute  the  main  installation  script  by  typing: 

. / install . sh 

The  script  prompts  you  for  input  as  needed;  just  follow  the  instructions. 

5.  Following  the  instructions  of  the  manual,  configure  Urchin  in  the 
directory  /hsphere/local/urchin. 

Note:  Urchin  port  and  owner  can  be  set  by  default  (9999,  nobody). 

6.  Create  directory  /hsphere/local/urchin/var/logs  by  running: 
mkdir  /hsphere/ local/ urchin/var/logs 

7.  Set  directory  owner  the  same  as  for  Urchin  on  step  5: 

chown  nobody : nobody  /hsphere/local/urchin/var/logs 

Important:  Make  steps  8-12  on  all  web  boxes. 

8.  Check  httpd.conf  for  Script  Alias  directive  in  the  shared  IP  Virtual  Host 
(usually  /hsphere /local / sqwebmail  directory).  If  this  directory 
doesn’t  exist  - create  it  with  755  permissions. 

9.  Copy  print-log  . pi  script  from  the  /hsphere/shared/scripts 

directory: 

cp  /hsphere/ shared/ scripts/print-log . pi 
/hsphere/ local/ sqwebmail/ cgi-bin/ 

10. Set  755  permissions  for  this  script: 

chmod  755  /hsphere/local/sqwebmail/cgi-bin/print-log . pi 

11. Create  loglist  file: 

touch  /hsphere/local/ sqwebmail/ cgi-bin/loglist 

12. Set  owner  and  group  for  this  file  to  httpd: 

chown  httpd: httpd  /hsphere/local/sqwebmail/cgi-bin/loglist 
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13. In  the  hsphere . properties  file,  configure  the  following  variables: 

- URCHINSERVERID  = [URCHIN_SERVER_ID] 

ID  of  the  logical  server  where  Urchin  is  installed.  You  can  get  the  logical  server 
ID  in  E. Manager 

- URCHINPORT  = [URCHINPORT] 
the  port  taken  by  Urchin 

■ URCHINSCHEDULERSTART  = [URCHINSCHEDULERSTART] 

■ URCHINSCHEDULERFINISH  = [SCHEDULERFINISH] 

the  hours  when  statistics  is  collected,  e.g,  2 and  4 means  statistics  will  be 
collected  between  2 and  4 AM 

- URCHINPROTOCOL  = [URCHIN_PROTOCOL] 

the  protocol  to  connect  to  the  Urchin  control  panel,  can  be  http  or  https.  The 
default  is  http 

■ URCHIN_SERVERNAME  = [URCHIN_SERVERNAME] 

Urchin  server  URL,  should  be  set  in  addition  to  URCPIIN_SERVER_ID  on 
systems  with  NAT  support  (on  page  28)  (the  Urchin  server  in  this  case  has  a 
local  IP).  In  other  cases,  you  should  comment  out  or  skip  setting  this  parameter. 

14. Restart  Parallels  H-Sphere  (on  page  41)  for  changes  to  take  effect. 


Urchin  4 and  5 Installation  on  Windows 

1.  Install  Urchin  as  instructed  by  the  Urchin  Installation  Guide  (Windows) 
at 

http://www.  google.  com/support/urchin45/bin/answer.py?answer=28546 

&topic=7372. 

2.  Log  in  to  Parallels  H-Sphere  control  panel  server  as  root. 

3.  In  the  hsphere . properties  file,  configure  the  following  variables: 

■ URCHIN_SERVER_ID  = <LSERVER_ID> 

ID  of  the  logical  server  where  Urchin4  is  installed 

■ URCH  IN_PORT  = <SERVER_PORT> 
port  where  Urchin  is  installed 

■ URCH  IN_SCHEDULER_S  TART  = <SCHEDULER_START_HOUR> 

• URCHIN_SCHEDULER_FINISH  = <SCHEDULER_STOP_HOUR> 

the  hours  when  statistics  is  collected,  e.g.  between  2 and  4 

■ urchin_protocoL  = <PROTOCOL> 

the  protocol  to  connect  to  the  Urchin  control  panel,  e.g.,  http  or  https. 

4.  Restart  HSphere  (on  page  41)  for  changes  to  take  effect. 
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Urchin  4 And  Urchin  5 Database  Utilities 
Urchin  Database  Utilities 

Urchin  4/5  installation  includes  utilities  to  insert,  edit,  and  delete  records  in  Urchin 
database.  The  only  two  ways  to  change  data  in  Urchin  internal  database  are  through 
Urchin  Control  Panel  or  by  the  means  of  Urchin  database  utilities. 

The  following  Urchin  database  utilities  are  located  in  the  util  subdirectory  of  the 
Urchin  installation  directory  (/hsphere/ shared/ urchin  for  Unix,  C : \Program 
Fiies\Urchin  for  Windows): 

■ uconf-import  (not  used  for  Parallels  H-Sphere  Windows  accounts)  is  a utility  that 
imports  XML  data  to  Urchin  database.  XML  data  may  be  transferred  to  the  standard 
input  or  taken  from  an  XML  file. 

For  more  details  on  uconf-import  options,  see  the  manual  on  the  Urchin 
Documentation  Center  at  http://help.urchin.com/index.cqi?id=1489 

■ uconf-driver  (uconf-driver.exe  for  Windows)  is  a utility  that  allows  inserting, 
deleting  or  updating  database  tables. 

Visit  Urchin  Documentation  Center  for  the  uconf-driver  options  at 
http://help.urchin.com/index.cqi?id=1 051 . 


Urchin  Database  Tables 

1.  Logfile  is  the  table  that  holds  log  file  locations.  In  Parallels  H-Sphere,  Urchin  log 
files  are  accessed  remotely  via  HTTP  protocol.  Log  file  is  returned  by  the  print- 
log,  pi  script. 

Here  is  an  example  of  XML  representaion  of  a Logfile  table  record: 

CLogfile  Name="urchin . com"> 
ct  name=urchin . com 
cr  type=remote 

ct  loglocation= /hsphere /local /urchin/ var/ logs/ 

cr_protocol=http 

ct  server=63 . 212 . 171 . 4 

ct_port=80 

ct  remotelocation=cgi-bin/print- 

log.pl?urchin&urchin. com&xgyvi jmuxpuad07plw/nuw==& . gz 
cs  logf ormat=ncsa 
</Logf ile> 

Field  description: 


Field  name 

XML  Representation 

Description 

Name 

<Logf ile 

Name="urchin . com" 

> 

Record  name,  coincides  with  the  domain  na 
in  Parallels  H-Sphere. 

ct  name 

ct  name=urchin . co 

m 

The  name  of  a domain  where  statistics  is 
collected. 
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cr  type 

cr  type=remote 

Type  of  access  to  log  files;  it  is  always  “remc 
in  Parallels  H-Sphere 

ct  loglocati 

on 

ct  loglocation=/h 
sphere/local/urch 
in/var/logs/ 

On  remote  access  to  this  directory,  log  files ' 
Web  boxes’  collected  statistics  are  taken. 

cr  protocol 

cr  protocol=http 

Protocol  used  to  access  log  files;  it  is  always 
“http”  in  Parallels  H-Sphere; 

ct  server 

ct  server=63 . 2 12 . 
171. 4 

IP  of  the  logical  server  where  log  files  are 
located. 

ct  remoteloc 

ation 

ct  remotelocation 
= cgi-bin/print- 
log.pl?urchin&urc 
hin . com&xgyvi jmux 
puad07plw/ nuw==S . 
gz 

Location  of  log  files;  in  Parallels  H-Sphere,  il 
set  as  the  URI  of  a CGI  script  that  collects 
statistics  from  remote  log  files,  with  a query 
string  containing  the  script  parameters. 

cs  logformat 

cs  logf ormat=ncsa 

Log  file  format:  ncsa  for  Unix,  w3c  for  Windi 

2.  Profile  is  a table  used  to  access  statistics  in  the  form  of  charts,  diagrams,  etc. 
Here  is  an  example  of  XML  representation  of  a Profile  table  record: 

<Profile  Name="urchin . com"> 
ct  name=urchin . com 
ct  website=http : //urchin . com 
ct  reportdomains=urchin . com, www . urchin . com 
cs  llist="urchin . com" 

</Prof ile> 

Table  field  description: 


Field  name 

XML  Representation 

Description 

Name 

<Prof ile 

Name="urchin. com"> 

Record  name,  coinsides  with  the 
domain  name  in  Parallels  H-Sphe 

ct  name 

ct  name=urchin . com 

The  name  of  a domain  where  sta 
is  being  collected. 

ct  website 

ct  website=http : //urchin 
. com 

Web  site  URL. 

ct  reportdomai 

ns 

ct  reportdomains=urchin . 
com, www . urchin . com 

Possible  ways  to  access  domain, 
domain  names  separated  with  co 

cs  Hist 

cs  llist="urchin . com" 

The  domain  where  log  file  is  loca 
this  field  is  used  to  link  this  table 
Logf  ile  table. 

3.  User  is  the  table  where  the  list  of  users  is  stored.  User  names  are  identical  to 
Parallels  H-Sphere  account  names.  Access  to  reports  is  also  set  in  this  table. 
Here  is  an  example  of  XML  representation  of  a Users  table  record: 

<User  Name="Urchin"> 
ct  name=Urchin 
ct_password=USCC | 3980261512 
cs  rlist="urchin . com" 

</User> 


Table  field  description: 


Field  name 


XML  Representation 


Description 


Name 

CUser  Name="Urchin"> 

Record  name,  coincides  with  the  domai 
name  in  Parallels  H-Sphere. 

ct  name 

ct  name=Urchin 

User  name. 

ct  passwor 
d 

ct  password=USCC | 398026 
1512 

User’s  password. 

cs  rlist 

cs  rlist="urchin . com" 

The  list  of  available  reports. 

4.  Task  is  the  table  that  contains  tasks  for  collecting  statistics. 

Here  is  an  example  of  XML  representation  of  a Task  table  record: 

CTask  Name="urchin . com"> 

ct  name=urchin . com 

cr  frequency=5 

cs  hour=4 

cs  minute=0 

</Task> 


Field  name 

XML  Representation 

Description 

Name 

CTask 

Name="urchin. corn'd 

Record  name,  coincides  with  the  domain  n; 
Parallels  H-Sphere. 

ct  name 

ct  name=urchin . com 

Domain  name. 

cr  freque 
ncy 

cr  frequency=5 

Task  launching  frequency;  5 means  it  wouli 
launch  every  24  hours. 

cs  hour 

cs  minute 

cs  hour=4, 
cs  minute=0 

Task  launching  time. 
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RealServer 

Parallels  H-Sphere  supports  all  versions  of  RealServer  that  have  ISPHosting  support.  If 
your  license  does  not  support  ISPHosting,  contact  your  RealServer  account 
representative  to  obtain  a license  key  that  has  the  same  number  of  streams  and 
properly  enables  ISP  hosting. 

In  this  chapter: 

RealServer  Installation  for  Unix 360 

RealServer  Installation  for  Windows 366 

RealServer  Config  File  Example 366 
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RealServer  Installation  for  Unix 


RealServer  can  be  installed  on  a web  box  or  a separate  box  with  apache. 

> To  install  RealServer  for  Unix: 

1.  Install  RealServer  with  ISPHosting  support  on  a web  box  or  a separate 
box  into  /hsphere/shared/RealServer  as  instructed  by  RealServer 
documentation  at  http://www.realnetworks.com/products/server/.  If  you 
set  it  up  on  a web  box,  specify  8080  port  instead  of  the  default  80, 
which  is  used  by  apache.  During  the  installation,  note  the  following 
data,  as  you  will  need  them  on  subsequent  steps: 

■ RealServer  IP 

■ RealServer  Admin  Port 

■ Administrator  Login 

■ Administrator  Password 

2.  Add  the  following  line  to  the  RealServer  crontab: 

0 7 * * * nice  -15 

/hsphere/ shared/ scripts/ cron/rmserver  analyze .pi 

3.  Launch  RealServer  with  the  following  command: 

/hsphere/shared/RealServer/Bin/rmserver  rmserver.cfg  & 

4.  Log  into  your  RealServer  interface  using  administrator  login  and 
password.  To  get  there,  type  this  URL  in  address  field  of  your  browser: 

http://RS  IP: ADMIN  PORT/admin/index . html 

replacing  rs_ip  and  admin_port  with  the  RealServer  IP  and  admin  port  you 
were  given  during  the  installation. 

5.  In  the  left  menu,  select  Server  Setup  ->  Mount  Points. 

6.  In  the  form  that  appears,  add  mount  point /shiva/  -> 

/hsphere/ local /home: 
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7.  Click  Apply.  The  status  window  will  open: 


Close  this  window. 


8.  Click  Restart  Server  in  the  upper  right  corner  of  the  browser  window  to 
restart  RealServer: 
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9.  Select  Content  Management  ->  ISP  Hosting  in  the  left  menu: 
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10. In  the  ISP  Hosting  form,  add  the  following  settings: 

Translation  Mounts : user 

User  List  File  Name',  /hsphere/local/ conf  ig/RealServer/user . list 

Description:  users 
Mount  Point:  /shiva/ 

User  Path:  / shiva/ 
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11. Click  Apply.  The  status  window  will  open: 


Close  this  window. 

12. Click  About  in  the  upper  left  corner  of  the  browser  window: 
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You  will  get  a window  with  information  about  your  license. 

13.  Go  to  the  admin  control  panel  and  add  the  box  to  Parallels  H-Sphere  as 
suggested  in  Adding  Servers  Step-By-Step  of  the  Service  Administrator 
Guide. 

14.  Now  you  can  proceed  to  RealServer  settings  that  are  not  related  to 
Parallels  H-Sphere. 

Here  is  an  example  of  RealServer  configuration  file: 
http://hsphere.parallels.com/HSdocumentation/svsadmin/rmserver.cfg.html. 


RealServer  Installation  for  Windows 

> To  install  RealServer  for  Windows: 

1.  Install  RealServer  with  ISPHosting  support 

2.  Add  mount  point  /shiva/  ->  /user’s_home_directory 

*You  can  learn  your  home  directory  in  the  conf . inc  file,  next  to  the  UserHome 
line. 

3.  Restart  RealServer. 

4.  After  that,  at  the  ISPHosting  page  in  the  Translation  Mounts  window: 
add  users  (Description:  users;  Mount  Point:  /shiva/;  User  Path:  /shiva/) 

add  user  list  (Edit  User  List  File  Name  in  the  directory  where  Parallels  H-Sphere  is 
installed:  /HSPhe re /Real Server/ user. list) 


RealServer  Config  File  Example 

<!— SYSTEM -> 

<Var  ProcessorCount="l"/> 

<!— PATHS --> 

<Var  LogPath="/var/hsphere/ rmserver/ rmaccess . log"/> 

<Var  ErrorLogPath="/var/hsphere/ rmserver/ rmerror . log"/> 

<Var  PidPath="/var/hsphere/ rmserver/ rmserver . pid"/> 

<Var  PluginDirectory="/hsphere/ shared/RealServer/Plugins"/> 

<Var  SupportPluginDirectory="/hsphere/ shared/ Real Server /Lib" /> 
<Var  LicenseDirectory="/hsphere/ shared/RealServer/License"/> 

<!-  PO  RTS  -> 

<!--UNIX  customers  must  have  root  privileges  to  execute  the 
server  --> 

<!--with  the  RTSP  port  set  to  554.  --> 

<!--The  following  are  the  default  ports  that  RealPlayer  and  --> 

<! --RealPlayer  Plus  clients  will  connect  to  for  an  URL  that  has 
— > 

<!— no  port  specified:  -->  <!--  RTSP:  554  -->  <!--  PNM:  7070  --> 
<!--  HTTP:  80  (...then  8080  if  80  is  unavailable)  --> 
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<Var  RTSPPort="554"/> 

<Var  PNAPort="7070"/> 

<Var  HTTPPort="8080"/> 

<Var  MonitorPort="9090"/> 

<Var  AdminPort="2 77 81 "/> 

<!-  PASSWORDS -> 

<Var  MonitorPassword="123456"/> 

<!--  ALLOWANCE --> 

<Var  ValidPlayersOnly="0"/> 

<Var  EnableCookieBasedIDs="0"/> 

<!-  LOGG  ING-> 

<Var  LoggingStyle="5"/>  <Var  StatsMask="3"/> 

<!-  LIVEARCHIVING-> 

CList  Name="LiveArchive"> 

<Li st  Name="* "> 

<Var  TargetDirectory="/Archive/"/> 

<Var  BandwidthNegotiation="0"/> 

<Var  FileSize="0"/> 

CVar  FileTime="0m0h0d"/> 

<Var  NoArchive="0"/> 

</List> 

</List> 

<!-  HTTP  S U P PO  RT-> 

<Li st  Name="HTTPDeliverable"> 

CVar  Path_0=" /admin" /> 

CVar  Path_l="/ramgen"/> 

CVar  Path_2="/farm"/> 

CVar  Path  3="/httpf s"/> 

CVar  Path  4="/viewsource"/> 

C/List> 

<!--  <Var  Path_0="/scalable"/>  --> 

<!-  MIMETYPES-> 

CList  Name="MimeTypes"> 

CList  Name="text/html"> 

CVar  Ext_l= "html " /> 

CVar  Ext_2="htm"/> 

C/List> 

CList  Name="audio/x-pn-realaudio"> 

CVar  Ext_l="ram"/> 

C/List> 

CList  Name="image/gif "> 

CVar  Ext_l="gif "/> 

C/List> 
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CList  Name="image/ jpg"> 

<Var  Ext_l=" jpg"/> 

<Var  Ext_2=" jpeg"/> 

</List> 

</List> 

<!- AUTHENTICATION -> 

<List  Name="AuthenticationRealms"> 

<List  Name="SecureAdmin"> 

<Var  Realm="ultra . shiva . AdminRealm"/> 

CList  Name="BasicAuthenticator"> 

CVar  PluginID="rn-auth-basic"/> 

CVar  DatabaseID="Admin  Basic"/> 

</List> 

</List> 

CList  Name="SecureEncoder"> 

CVar  Realm="ultra . shiva . EncoderRealm"/> 

CList  Name="RN5Authenticator"> 

CVar  PluginID="rn-auth-rn5"/> 

CVar  DatabaseID="Encoder  RN5"/> 

C/List> 

C/List> 

CList  Name="SecureContent"> 

CVar  Realm="ultra . shiva . ContentRealm"/> 

CList  Name="RN5Authenticator"> 

CVar  PluginID="rn-auth-rn5"/> 

CVar  DatabaseID="Content  RN5"/> 

C/List> 

C/List> 

C/List> 

<!-  COMMERCE -> 

CList  Name="CommerceRules"> 

CList  Name="SecureUserContent"> 

CVar  ProtectedVirtualPath="/ secure"/> 

CVar  Realm="ultra . shiva . ContentRealm"/> 
c!--  CVar  UseGUIDValidation="True"/  --> 

CVar  EvaluatePermissions="0"/> 

CVar  DatabaseID="Content  RN5"/> 

c!--  CVar  AllowDuplicateIDs="True"/  --> 

C/List> 

CList  Name="SecureG2LiveContent"> 

CVar  ProtectedVirtualPath="/ encoder/ secure"/> 
CVar  Realm="ultra . shiva . ContentRealm"/> 

C ! — CVar  UseGUIDValidation="True"/  --> 
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<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="Content  RN5"/> 

< ! — <Var  AllowDupli cate IDs= "True"/  — > 

</List> 

<List  Name="SecurePreG2LiveContent"> 

<Var  ProtectedVirtualPath="/live/ secure" /> 

<Var  Realm="ultra . shiva . ContentRealm"/> 

< ! — <Var  UseGUIDValidation="True"/  — > 

<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="Content  RN5"/> 

< ! — <Var  AllowDupli cate IDs= "True"/  — > 

</List> 

<List  Name="SecurePlayerContent"> 

<Var  ProtectedVirtualPath="/ secure/player"/> 
<Var  UseGUIDValidation="0"/> 

<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="PlayerContent"/> 

<! — <Var  AllowDuplicateIDs="True"/  — > 

</List> 

</List> 

<List  Name="GUIDRegistrationPref ixes"> 

<List  Name="PlayerContentRegistration"> 

<Var  GUIDRegistrationPref ix=" register "/> 

<Var  DatabaseID="PlayerContent"/> 

</List> 

</List> 

<!-  DATABASES --> 

<List  Name="Databases"> 

<List  Name="Admin  Basic"> 

<Var  PluginID="rn-db-flatfile"/> 

<Var  Path="/hsphere/shared/RealServer/adm  b db"/> 
</List> 

<List  Name="Encoder  RN5"> 

<Var  PluginID="rn-db-flatfile"/> 

<Var  Path="/hsphere/shared/RealServer/enc  r db"/> 
</List> 

<List  Name="Content  RN5"> 

<Var  PluginID="rn-db-flatfile"/> 

<Var  Path="/hsphere/shared/RealServer/con  r db"/> 
</List> 

<List  Name="PlayerContent"> 

<Var  PluginID="rn-db-flatfile"/> 

<Var  Path="/hsphere/shared/RealServer/con  p db"/> 
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</List> 

</List> 

<!- VI  EWSOU  RCE-> 

<List  Name="ViewSourceConf iguration"> 

<Var  ViewSourceLongName="View  Source  Tag  FileSystem"/> 

<List  Name="/"> 

<Var  AllowViewSource="l"/> 

<Var  HidePaths="l "/> 

</List> 

</List> 

<!--  CONTENTBROWSINIG~> 

<List  Name="ContentBrowsing"> 

<List  Name="BrowsableMountPoints"> 

<Var  Mount_l="/"/> 

<Var  Mount_2="/shiva/"/> 

</List> 

<List  Name="IndexExtensions"> 

<Var  Ext_l="*"/> 

</List> 

</List> 

<!-  FI  LESYSTEMS-> 

< ! — --> 

<List  Name="FSMount"> 

<!--  Local  File  System;  Media  --> 

CList  Name="RealSystem  Content"> 

<Var  ShortName="pn-local"/> 

<Var  Mount Point="/"/> 

<Var  BasePath="/hsphere/ shared/RealServer/ Content"/> 
</List> 

<!--  Local  File  System;  Secure  Media  --> 

<List  Name="RealSystem  Secure  Content"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint="/secure/"/> 

<Var  BasePath="/hsphere/ shared/RealServer/ Secure"/> 

</List> 

<!--  Local  File  System;  HTML  --> 

<List  Name="RealSystem  Administrator  HTML"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint="/admin/html/"/> 

<Var 

BasePath="/hsphere/ shared/ Real Server /RealAdministrator"/> 
</List> 
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<!--  Local  File  System;  DOCS  --> 

<List  Name="RealSystem  Administrator  DOCS"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint="/admin/Docs/"/> 

<Var 

BasePath="/hsphere/ shared/RealServer /Real Administrator /Docs "/> 
</List> 

<!--  Local  File  System;  IMAGES  --> 

<List  Name="RealSystem  Administrator  IMAGES"> 

<Var  ShortName="pn-local"/>  <Var  MountPoint="/admin/images/"/> 
<Var 

BasePath="/hsphere/ shared/Real Server /Real Administrator/ images "/> 
</List> 

<!-  Local  File  System;  JAVAMONITOFt  -> 

<List  Name="RealSystem  Administrator  JAVAMONITOR"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint="/admin/ JavaMonitor/"/> 

<Var 

BasePath="/hsphere/ shared/Real Server /Real Administrator/ JavaMonit 

or"/> 

</List> 

<!--  XML  Tag  Flandler  File  System  -> 

<List  Name="Real  System  Administrator  SSI"> 

<Var  ShortName="pn-xmltag"/> 

<Var  Mount Point=" /admin/ include s/"/> 

<Var  BaseMountPoint="/admin/html/"/> 

<List  Name="TagHandlers"> 

<Var  hl="pn-includer"/> 

<Var  h2="pn-vsrctaghdlr"/> 

</List> 

</List> 

<!--  Admin  File  System  --> 

<List  Name="RealSystem  Administrator  Files"> 

<Var  ShortName="pn-admin"/> 

<Var  MountPoint="/admin/"/> 

<Var  BaseMountPoint="/ admin/ include s/"/> 

<Var  Realm="ultra . shiva . AdminRealm"/> 

</List> 

<!--  Splitter  Broadcast  --> 

<List  Name="Splitter_DoubleURL"> 

<Var  ShortName="pn-splitter"/> 

<Var  MountPoint=" /split/ "/> 

<Var  Port="3030"/> 

</List> 
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<!--  G2  Encoders  --> 

<List  Name="RealSystem  G2  Encoders'^ 

<Var  ShortName="pn-encoder"/> 

<Var  MountPoint="/encoder/"/> 

<Var  Port="4040"/> 

<Var  EncoderRealm="ultra . shiva . EncoderRealm"/> 
</List> 

<!--  Pre-G2  Encoders  --> 

<List  Name="Pre-RealSystem  G2  Encoders'^ 

<Var  ShortName="pn-live3"/> 

<Var  MountPoint="/live/"/> 

<Var  Port="5050"/> 

<!--  Var  Password="123456"/  --> 

</List> 

<!--  RAM  File  Generator -> 

<List  Name="RAM  File  Generator"> 

<Var  ShortName="pn-ramgen"/> 

<Var  MountPoint="/ramgen/"/> 

</List> 

<!--  View  Source  File  system  --> 

<List  Name="View  Source  File  System"> 

<Var  ShortName="pn-vsrcf sys"/> 

<Var  MountPoint="/vsrcf sys/"/> 

</List> 

<!--  View  Source  Tag  File  System;  Source  Insertion  --> 

<List  Name="View  Source  Tag  FileSystem"> 

<Var  ShortName="pn-xmltag"/> 

<Var  MountPoint="/viewsource/"/> 

<Var  BaseMountPoint="/vsrcf sys/"/> 

CList  Name="TagHandlers"> 

<List  Name="ViewSource  Tag  Handler"> 

<Var  ShortName="pn-vsrctaghdlr"/> 

</List> 

</List> 

</List> 

<!--  General  Ad  Insertion  ~> 

<List  Name="General  Ad  Insertion"> 

<Var  ShortName="pn-xmltag"/> 

<Var  Mount Point="/adtag/ general /"/> 

<Var  BaseMountPoint="/"/> 

<List  Name="TagHandlers"> 

<List  Name="Ad  Tag  Replacement  Plugin"> 
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<Var  ShortName="rn-adtaghandler"/> 

<Var  AdRetrievalMountPoint="/httpf s/"/> 

<Var  AdPlaybackMountPoint="/httpf s/"/> 

<Var  AdURL="http: //www. real . com/ads/g2ads  def.html"/> 

<Var  Rotate="0"/>  <Var  Bitrate="4000"/> 

<Var  Interval="30"/>  <Var  RotationMountPoint="/shellf s/"/> 
</List> 

</List> 

</List> 

<!-  Banner  Ad  SMIL  Generation  --> 

<List  Name="Banner  Ad  SMIL  Generation"> 

<Var  ShortName="pn-smilgen"/> 

<Var  MountPoint="/ smilgen/banner/"/> 

<Var  BaseMountPoint="/"/> 

<Var  Layout="AdBottom"/> 

<Var  0uterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor= "black" /> 

<Var  AdType="Banner"/> 

<Var  EnablePlaylist="0"/> 

<Var  AdWidth="4  68"/> 

<Var  AdHeight="60"/> 

</List> 

<!--  Lead-in  Ad  SMIL  Generation  -> 

<List  Name="Lead-in  Ad  SMIL  Generation"> 

<Var  ShortName="pn-smilgen"/> 

<Var  MountPoint="/ smilgen/leadin/"/> 

<Var  BaseMountPoint="/"/> 

<Var  Layout="AdCenter"/> 

<Var  0uterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor="black"/> 

<Var  AdType="Leadin"/> 

<Var  EnablePlaylist="0"/> 

<Var  AdWidth="4 68"/> 

<Var  AdHeight="60"/> 

</List> 

<!-  Continuous  Rotating  Banner  Ad  SMIL  Generation  -> 

CList  Name="Continuous  Rotating  Banner  Ad  SMIL  Generation"> 
<Var  ShortName="pn-smilgen"/> 

<Var  MountPoint="/ smilgen/ rbanner/"/> 

<Var  BaseMountPoint="/"/> 
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<Var  Layout="AdBottom"/> 

<Var  OuterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor= "black" /> 

<Var  AdType="RotatingBanner"/> 

<Var  EnablePlaylist="0"/> 

<Var  AdWidth="4  68"/> 

<Var  AdHeight="60"/> 

</List> 

<!--  HTTP  File  System  --> 

<Li st  Name="HTTP  File  System"> 

<Var  ShortName="pn-http"/> 

<Var  MountPoint="/httpf s/"/> 

<Var  ConnectionTimeout="10"/> 

<Var  ServerTimeout="10"/> 

<Var  MangleCookies="0"/> 

</List> 

<!--  RealSystem  Shell  File  System  --> 

<List  Name="RealSystem  Shell  File  System"> 

<Var  ShortName="pn-shell"/> 

<Var  MountPoint="/shellf s/"/> 

<Var  AdRetrievalMountPoint="/httpf s/"/> 

<Var  AdPlaybackMountPoint="/httpf s/"/> 

</List> 

<List  Name="Users"> 

<Var  MountPoint="/shiva/"/> 

<Var  BasePath="/hsphere/local/ real/home/"/> 

<Var  ShortName="pn-local"/> 

</List> 

</List> 

<!-  C AC  H I N G --> 

<Var  TSPort="7802"/> 

<Var  TSEnable="l"/> 

<Var  TSLog="l"/> 

<Var  TSLogPath="/hsphere/ shared/RealServer/Logs/ cache . log"/> 

<!-  MULTICAST -> 

<List  Name="Multicast"> 

<List  Name="ControlList"> 

<List  Name="100"> 

CVar  Allow="Any"/> 

</List> 

</List> 

<Var  RTSPPort="554"/> 
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<Var  PNAPort="7  070"/> 

<Var  DeliveryOnly="0"/> 

<Var  Resend="l"/> 

<Var  TTL="16"/> 

</List> 

<List  Name="MediaExportInterf ace"> 

<Var  LogFile="/hsphere/ shared/RealServer/Logs/ cache . log"/> 
<Var  LoggingEnabled="l"/> 

<Var  Transf erSize="2048"/> 

<Var  Enabled="l"/> 

<Var  ListenPort="7878"/> 

<Var  ChainingID="007b4603"/> 

<Var  Tracemask="OxO"/> 

<Var  LogFormat="MEIl"/> 

CVar  Timeout="120"/> 

</List> 

<Var  CloakingHint="l"/> 

CVar  Capacity="10000"/> 

CVar  PlusOnly="0"/> 

CVar  MaxBandwidth="0"/> 

CVar  User="%-l"/> 

CVar  RTSPMessageDebug="0"/> 

CVar  LiveFileBandwidthNegotiation="0"/> 

CVar  MonitorConnections="4"/> 

CVar  Group="%-l"/> 

CVar  MinPlayerProtocol="0"/> 

CVar  ClientConnections="0"/> 

CList  Name="ISPHosting"> 

CList  Name="TranslationMounts"> 

CList  Name="users"> 

CVar  UserPath="/shiva/"/> 

CVar  MountPoint="/shiva/"/> 

C/List> 

C/List> 

CList  Name="UserLists"> 

CVar  File  2="/hsphere/local/conf ig/RealServer/user . list"/> 

C/List> 

C/List> 
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Softaculous 


Softaculous  (http://www.softaculous.com/)  is  an  auto  installer  of  web  applications.  It  is 
a third-party  software  that  can  be  installed  on  H-Sphere-managed  web  servers.  Only 
UNIX  boxes  are  supported. 

In  this  chapter: 
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Softaculous  Installation  for  Unix 


There  are  two  steps  in  Softaculous  installation.  First  you  need  to  install  Softaculous  on 
each  UNIX  box.  This  process  is  described  in  documentation  provided  by  Softaculous. 
At  the  second  step,  you  should  enable  Softaculous  support  in  Fl-Sphere. 

> To  install  Softaculous: 

1.  Enable  PHP  and  set  PHP  5 as  default  PHP  version  on  all  Unix  web 
servers  on  page  Enterprise  Manager  / Physical  Servers  / <unix  server>  / 
“Physical  Server  Parameters”  button  / PHP  Configuration. 

2.  Follow  the  Softaculous  installation  instructions  and  install  Softaculous 
on  each  of  the  UNIX  boxes  separately.  Installation  should  be  done  in 
the  directory  <apache_def ault_document_root>,  value  can  be 
found  in  config  files 

/hsphere/ shared/ apache/ conf / lservers / web_<service_id> . conf 
/hsphere/ shared/ apache2/conf /lservers/web_<service_id> . conf 

, depending  on  apache  version. 

Normally  <apache_default_document_root>  setting  is 
/hsphere/ shared/ apache/htdocs. 

3.  Enable  Softaculous  in  Fl-Sphere: 

■ Log  into  your  CP  server  as  the  cpanel  user  (see  page  53). 

■ Open  hsphere  . properties  file: 

vi  ~cpanel/ shiva/psof t_conf ig/hsphere . properties 

■ Uncomment  the  Softaculous  settings  as  displayed  below: 

SOFTACULOUS_URL=sof taculous/ 

SOFTACULOUS_ADMIN_URL=softaculous -admin/ 

, where  softaculous_url  and  softaculous_admin_url  is  the  path  on 
UNIX  box  document  root  to  Softaculous  user  and  administrator  interface 
respectively. 

■ Open  the  config  file  allow_access  . properties: 

vi  ~cpanel/shiva/psoft_config/allow_access .properties 

■ Allow  access  to  Fl-Sphere  XML  API  from  the  Unix  boxes  where  Softaculous  has 
been  enabled.  Add  the  following  line: 

ACCESS_ALLOW  = <client_ipl>;<client_ip2>;< . . .> 

(see  page 

http://www.psoft.net/FISdocumentation/devel/hs  xml  api  security.html#access 

allow  for  details) 

■ Restart  the  Fl-Sphere  control  panel  (see  page  41). 

4.  Log  in  as  a site  administrator  and  verify  that  Softaculous  button  is 
displayed  on  page  Enterprise  Manager  / Logical  Servers  / <Logical 
server>  / Additional  options. 

5.  Log  in  as  a site  user  and  verify  that  Softaculous  button  is  displayed  on 
page  Web  Options. 


